From 0946641dce6647dbe239edef4cc168a9e304ac39 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Fri, 30 Jan 2026 15:23:56 -0700 Subject: [PATCH 1/9] docs: Add experts system specification and initial standard expert Add specification for the experts system - auto-improving collections of domain knowledge that get exposed as Claude agents. - Add doc/experts_requirements.md with full specification: - Directory structure (.deepwork/experts/[name]/) - File formats (expert.yml, topics/*.md, learnings/*.md) - CLI commands (deepwork topics, deepwork learnings) - Sync behavior (generates agents in .claude/agents/) - Add initial "experts" standard expert in src/deepwork/standard/experts/: - Meta-expert for the experts system itself - Topics on design patterns and discovery descriptions - Update doc/architecture.md: - Add src/deepwork/standard/ directory to structure diagram - Add "Experts (Planned)" section Co-Authored-By: Claude Opus 4.5 --- doc/architecture.md | 25 ++- doc/experts_requirements.md | 165 +++++++++++++++ .../standard/experts/experts/expert.yml | 194 ++++++++++++++++++ .../experts/experts/learnings/.gitkeep | 0 .../experts/topics/discovery_descriptions.md | 83 ++++++++ .../experts/topics/expert_design_patterns.md | 69 +++++++ 6 files changed, 535 insertions(+), 1 deletion(-) create mode 100644 doc/experts_requirements.md create mode 100644 src/deepwork/standard/experts/experts/expert.yml create mode 100644 src/deepwork/standard/experts/experts/learnings/.gitkeep create mode 100644 src/deepwork/standard/experts/experts/topics/discovery_descriptions.md create mode 100644 src/deepwork/standard/experts/experts/topics/expert_design_patterns.md diff --git a/doc/architecture.md b/doc/architecture.md index f4a2e094..795f51f7 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -63,7 +63,7 @@ deepwork/ # DeepWork tool repository │ │ │ └── skill-job-step.md.jinja │ │ ├── gemini/ │ │ └── copilot/ -│ ├── standard_jobs/ # Built-in job definitions +│ ├── standard_jobs/ # Built-in job definitions (legacy location) │ │ ├── deepwork_jobs/ │ │ │ ├── job.yml │ │ │ ├── steps/ @@ -77,6 +77,13 @@ deepwork/ # DeepWork tool repository │ │ ├── global_hooks.yml │ │ ├── user_prompt_submit.sh │ │ └── capture_prompt_work_tree.sh +│ ├── standard/ # Standard assets (new consolidated location) +│ │ └── experts/ # Built-in expert definitions +│ │ └── experts/ # Meta-expert for the experts system itself +│ │ ├── expert.yml +│ │ ├── topics/ +│ │ └── learnings/ +│ │ └── .gitkeep │ ├── schemas/ # Definition schemas │ │ ├── job_schema.py │ │ ├── doc_spec_schema.py # Doc spec schema definition @@ -1344,6 +1351,22 @@ Claude: Created rule "API documentation update" in .deepwork/rules/api-documenta --- +## Experts (Planned) + +Experts are auto-improving collections of domain knowledge. They provide a structured mechanism for accumulating expertise and exposing it through Claude agents. + +**Status**: Specification complete, implementation pending. + +See `doc/experts_requirements.md` for the full specification. + +**Key Concepts**: +- Experts live in `.deepwork/experts/[name]/` with `expert.yml`, `topics/`, and `learnings/` +- Standard experts ship from `src/deepwork/standard/experts/` and are installed during `deepwork install` +- `deepwork sync` will generate Claude agents in `.claude/agents/` with `dwe_` prefix +- CLI commands: `deepwork topics --expert "name"` and `deepwork learnings --expert "name"` + +--- + ## Technical Decisions ### Language: Python 3.11+ diff --git a/doc/experts_requirements.md b/doc/experts_requirements.md new file mode 100644 index 00000000..7906b8f2 --- /dev/null +++ b/doc/experts_requirements.md @@ -0,0 +1,165 @@ +# Experts System + +> **Status**: Specification complete, implementation pending. This document describes planned functionality. + +Experts are auto-improving collections of domain knowledge. They provide a structured mechanism for accumulating expertise and exposing it throughout the system. + +## Overview + +Each expert represents deep knowledge in a specific domain (e.g., "Ruby on Rails ActiveJob", "Social Marketing"). Experts consist of: +- **Core expertise**: The foundational knowledge about the domain +- **Topics**: Detailed documentation on specific subjects within the domain +- **Learnings**: Hard-fought insights from real experiences + +## Directory Structure + +Experts live in `.deepwork/experts/[expert-folder-name]/`: + +``` +.deepwork/experts/ +└── rails_activejob/ + ├── expert.yml # Core expert definition + ├── topics/ # Detailed topic documentation + │ └── retry_handling.md + └── learnings/ # Experience-based insights + └── job_errors_not_going_to_sentry.md +``` + +### Naming Convention + +The **expert name** is derived from the folder name: +- Spaces and underscores become dashes +- Example: folder `rails_activejob` → expert name `rails-activejob` +- This name is used in CLI commands: `deepwork topics --expert "rails-activejob"` + +## File Formats + +### expert.yml + +```yaml +discovery_description: | + Short description used by other parts of the system to decide + whether to invoke this expert. Keep it concise and specific. + +full_expertise: | + Unlimited text (but generally ~5 pages max) containing the + complete current knowledge of this domain. This is the core + expertise that gets included in the generated agent. +``` + +**Note**: The expert name is not a field in this file—it's derived from the folder name. + +### topics/*.md + +Topics are frontmatter Markdown files covering specific subjects within the domain. + +```markdown +--- +name: Retry Handling +keywords: + - retry + - exponential backoff + - dead letter queue +last_updated: 2025-01-15 +--- + +Detailed documentation about retry handling in ActiveJob... +``` + +| Field | Description | +|-------|-------------| +| `name` | Human-readable name (e.g., "Retry Handling") | +| `keywords` | Topic-specific keywords only—avoid broad terms like "Rails" | +| `last_updated` | Date stamp (manually maintained) | + +Filenames are purely organizational and don't affect functionality. + +### learnings/*.md + +Learnings document complex experiences and hard-fought insights—like mini retrospectives. + +```markdown +--- +name: Job errors not going to Sentry +last_updated: 2025-01-20 +summarized_result: | + Sentry changed their standard gem for hooking into jobs. + SolidQueue still worked but ActiveJobKubernetes did not. +--- + +## Context +We noticed errors from background jobs weren't appearing in Sentry... + +## Investigation +After debugging, we discovered that Sentry's latest gem update... + +## Resolution +Updated the initialization to explicitly configure the hook... +``` + +| Field | Description | +|-------|-------------| +| `name` | Human-readable title of the learning | +| `last_updated` | Date stamp (manually maintained) | +| `summarized_result` | Brief summary of the key finding | + +## CLI Commands + +### List Topics + +```bash +deepwork topics --expert "rails-activejob" +``` + +Returns a Markdown list of topics: +- Name and relative file path as a Markdown link +- Followed by keywords +- Sorted by most-recently-updated + +### List Learnings + +```bash +deepwork learnings --expert "rails-activejob" +``` + +Returns a Markdown list of learnings: +- Name and relative file path as a Markdown link +- Followed by the summarized result +- Sorted by most-recently-updated + +## Sync Behavior + +`deepwork sync` generates Claude agents from experts (in addition to syncing jobs). + +### Generated Agent Location + +Agents are created in `.claude/agents/` with: +- **Filename**: `dwe_[expert-name].md` (e.g., `dwe_rails-activejob.md`) +- **name field**: `[expert-name]-expert` (e.g., `rails-activejob-expert`) +- **description**: The `discovery_description` from expert.yml + +### Agent Body Content + +The agent body combines: +1. The `full_expertise` text +2. A topics list using Claude's dynamic command embedding: + ``` + $(deepwork topics --expert "rails-activejob") + ``` +3. A learnings list using the same mechanism: + ``` + $(deepwork learnings --expert "rails-activejob") + ``` + +This ensures the agent always has access to the latest topics and learnings at runtime. + +## Standard Experts + +Standard experts ship with DeepWork and are located at `src/deepwork/standard/experts/`. + +When `deepwork install` runs, these are copied into `.deepwork/experts/` in the target project. + +## Future Considerations + +- Experts and jobs are currently independent systems +- Future versions may enable experts to reference each other and collaborate with jobs diff --git a/src/deepwork/standard/experts/experts/expert.yml b/src/deepwork/standard/experts/experts/expert.yml new file mode 100644 index 00000000..94cced9c --- /dev/null +++ b/src/deepwork/standard/experts/experts/expert.yml @@ -0,0 +1,194 @@ +discovery_description: | + DeepWork experts system - creating, organizing, and evolving domain knowledge + collections that auto-improve through topics and learnings. + +full_expertise: | + # DeepWork Experts System + + You are an expert on the DeepWork experts system - the framework for building + auto-improving collections of domain knowledge. + + ## Core Concepts + + **Experts** are structured knowledge repositories that grow smarter over time. + Each expert represents deep knowledge in a specific domain and consists of: + + - **Core expertise**: Foundational knowledge captured in expert.yml + - **Topics**: Detailed documentation on specific subjects + - **Learnings**: Hard-fought insights from real experiences + + ## When to Create an Expert + + Create an expert when: + - You have recurring work in a specific domain + - Knowledge is scattered and needs consolidation + - You want to capture learnings that would otherwise be lost + - A domain has enough depth to warrant structured documentation + + Do NOT create an expert for: + - One-off tasks with no future relevance + - Domains too broad to be actionable (e.g., "Programming") + - Topics better served by external documentation + + ## Expert Structure + + Experts live in `.deepwork/experts/[folder-name]/`: + + ``` + .deepwork/experts/ + └── rails_activejob/ + ├── expert.yml + ├── topics/ + │ └── retry_handling.md + └── learnings/ + └── job_errors_not_going_to_sentry.md + ``` + + The **expert name** derives from the folder name with spaces/underscores becoming + dashes: `rails_activejob` → `rails-activejob`. + + ## Writing Good expert.yml + + The expert.yml has two key fields: + + ### discovery_description + A concise description (1-3 sentences) that helps the system decide when to + invoke this expert. Be specific about the domain and capabilities. + + Good: "Ruby on Rails ActiveJob - background job processing, retries, queues, + and error handling in Rails applications." + + Bad: "Helps with Rails stuff." + + ### full_expertise + The core knowledge payload (~5 pages max). Structure it as: + + 1. **Identity statement**: "You are an expert on..." + 2. **Core concepts**: Key ideas and mental models + 3. **Common patterns**: Typical approaches and solutions + 4. **Pitfalls to avoid**: Known gotchas and mistakes + 5. **Decision frameworks**: How to choose between options + + Write in second person ("You should...") as this becomes agent instructions. + + ## Writing Good Topics + + Topics are deep dives into specific subjects within the domain. + + ### When to create a topic + - Subject needs more detail than fits in full_expertise + - You find yourself repeatedly explaining something + - A subject has enough nuance to warrant dedicated documentation + + ### Topic file structure + ```markdown + --- + name: Retry Handling + keywords: + - retry + - exponential backoff + - dead letter queue + last_updated: 2025-01-15 + --- + + [Detailed content here] + ``` + + ### Keyword guidelines + - Use topic-specific terms only + - Avoid broad domain terms (don't use "Rails" in a Rails expert's topics) + - Include synonyms and related terms users might search for + - 3-7 keywords is typical + + ## Writing Good Learnings + + Learnings capture hard-fought insights from real experiences - like mini + retrospectives that prevent repeating mistakes. + + ### When to create a learning + - You solved a non-obvious problem + - A debugging session revealed unexpected behavior + - You discovered something that contradicts common assumptions + - Future-you would benefit from this context + + ### Learning file structure + ```markdown + --- + name: Job errors not going to Sentry + last_updated: 2025-01-20 + summarized_result: | + Sentry changed their standard gem for hooking into jobs. + SolidQueue still worked but ActiveJobKubernetes did not. + --- + + ## Context + What was happening and why it mattered... + + ## Investigation + What you tried and what you discovered... + + ## Resolution + How you fixed it and why that worked... + + ## Key Takeaway + The generalizable insight for future reference... + ``` + + ### summarized_result guidelines + - 1-3 sentences capturing the key finding + - Should be useful even without reading the full body + - Focus on the "what" not the "how" + + ## CLI Commands + + ### Listing topics + ```bash + deepwork topics --expert "expert-name" + ``` + Returns markdown list with links, keywords, sorted by last_updated. + + ### Listing learnings + ```bash + deepwork learnings --expert "expert-name" + ``` + Returns markdown list with links, summaries, sorted by last_updated. + + ## How Experts Become Agents + + Running `deepwork sync` generates Claude agents in `.claude/agents/`: + + - Filename: `dwe_[expert-name].md` + - Agent name: `[expert-name]-expert` + - Body: full_expertise + dynamic topic/learning lists + + The dynamic embedding ensures agents always access current topics and learnings: + ``` + $(deepwork topics --expert "expert-name") + $(deepwork learnings --expert "expert-name") + ``` + + ## Evolution Strategy + + Experts should evolve through use: + + 1. **Start minimal**: Begin with core expertise, add topics/learnings as needed + 2. **Capture immediately**: Document learnings right after solving problems + 3. **Refine periodically**: Review and consolidate as patterns emerge + 4. **Prune actively**: Remove outdated content, merge redundant topics + + ## Naming Conventions + + ### Expert folders + - Use lowercase with underscores: `rails_activejob`, `social_marketing` + - Be specific enough to be useful: `react_hooks` not just `react` + - Avoid redundant words: `activejob` not `activejob_expert` + + ### Topic files + - Use lowercase with underscores: `retry_handling.md` + - Name describes the subject: `queue_configuration.md` + - Filenames are organizational only - the `name` frontmatter is displayed + + ### Learning files + - Use lowercase with underscores: `job_errors_not_going_to_sentry.md` + - Name captures the problem or discovery + - Can be longer/descriptive since they're not referenced programmatically diff --git a/src/deepwork/standard/experts/experts/learnings/.gitkeep b/src/deepwork/standard/experts/experts/learnings/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/deepwork/standard/experts/experts/topics/discovery_descriptions.md b/src/deepwork/standard/experts/experts/topics/discovery_descriptions.md new file mode 100644 index 00000000..f68112b9 --- /dev/null +++ b/src/deepwork/standard/experts/experts/topics/discovery_descriptions.md @@ -0,0 +1,83 @@ +--- +name: Writing Discovery Descriptions +keywords: + - discovery + - description + - routing + - selection +last_updated: 2025-01-30 +--- + +# Writing Effective Discovery Descriptions + +The `discovery_description` determines when your expert gets invoked. It's the +"elevator pitch" that helps the system route queries to the right expert. + +## Purpose + +Discovery descriptions are used by other parts of the system to decide: +- Whether to suggest this expert for a task +- Which expert to invoke when multiple could apply +- How to present the expert to users + +## Anatomy of a Good Description + +```yaml +discovery_description: | + Ruby on Rails ActiveJob - background job processing including + queue configuration, retry strategies, error handling, and + integration with queue backends like Sidekiq and SolidQueue. +``` + +Components: +1. **Domain identifier**: "Ruby on Rails ActiveJob" +2. **Core capability**: "background job processing" +3. **Specific coverage**: "queue configuration, retry strategies..." +4. **Boundaries**: "integration with queue backends like..." + +## Guidelines + +### Be Specific +Bad: "Helps with background jobs" +Good: "Rails ActiveJob background processing - queues, retries, error handling" + +### Include Key Terms +Include terms users would search for. If someone asks about "Sidekiq retries", +the description should contain those words. + +### Set Boundaries +Indicate what's in and out of scope. "...including X, Y, Z" signals coverage. + +### Keep It Scannable +1-3 sentences max. The system needs to quickly evaluate relevance. + +### Avoid Marketing Speak +Bad: "The ultimate guide to mastering background jobs" +Good: "ActiveJob configuration, error handling, and queue backend integration" + +## Examples + +### Too Vague +```yaml +discovery_description: Helps with Rails development +``` + +### Too Narrow +```yaml +discovery_description: How to configure exponential backoff in ActiveJob +``` + +### Just Right +```yaml +discovery_description: | + Rails ActiveJob expertise - background job processing, queue + configuration, retry strategies, error handling, and integration + with Sidekiq, SolidQueue, and other queue backends. +``` + +## Testing Your Description + +Ask yourself: +1. If I had this problem, would I find this expert? +2. Does it differentiate from similar experts? +3. Can I tell what's covered in 5 seconds? diff --git a/src/deepwork/standard/experts/experts/topics/expert_design_patterns.md b/src/deepwork/standard/experts/experts/topics/expert_design_patterns.md new file mode 100644 index 00000000..3ce13a61 --- /dev/null +++ b/src/deepwork/standard/experts/experts/topics/expert_design_patterns.md @@ -0,0 +1,69 @@ +--- +name: Expert Design Patterns +keywords: + - patterns + - structure + - organization + - best practices +last_updated: 2025-01-30 +--- + +# Expert Design Patterns + +Common patterns for structuring effective experts. + +## The Layered Knowledge Pattern + +Structure expertise from general to specific: + +1. **full_expertise**: Core concepts, decision frameworks, common patterns +2. **topics/**: Deep dives into specific subjects +3. **learnings/**: Concrete experiences and edge cases + +This mirrors how humans learn - start with foundations, then specialize. + +## The Problem-Solution Pattern + +For domains centered around solving problems: + +- **full_expertise**: Problem categories, diagnostic approaches, solution frameworks +- **topics/**: Specific problem types with detailed solutions +- **learnings/**: Real debugging sessions and unexpected fixes + +Works well for: troubleshooting guides, error handling, debugging domains. + +## The Reference Pattern + +For domains with lots of factual information: + +- **full_expertise**: Overview, when to use what, quick reference +- **topics/**: Detailed reference on specific APIs, configs, options +- **learnings/**: Gotchas and undocumented behaviors + +Works well for: API documentation, configuration guides, tool references. + +## The Process Pattern + +For domains with sequential workflows: + +- **full_expertise**: Overall process, decision points, success criteria +- **topics/**: Detailed steps for each phase +- **learnings/**: Process failures and improvements + +Works well for: deployment procedures, review processes, onboarding. + +## Anti-Patterns to Avoid + +### The Kitchen Sink +Cramming everything into full_expertise. If it's over 5 pages, split into topics. + +### The Empty Shell +Creating expert.yml with minimal content and empty topics/learnings folders. +Start with meaningful content or don't create the expert yet. + +### The Stale Expert +Never updating after initial creation. Set a reminder to review quarterly. + +### The Duplicate Expert +Creating overlapping experts. Better to have one comprehensive expert than +several fragmented ones. From 074232202ddfc31e127f7ceeb2a2184884596937 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Fri, 30 Jan 2026 15:47:52 -0700 Subject: [PATCH 2/9] Experts added --- .claude/agents/dwe_experts.md | 210 +++++++ .deepwork/experts/experts/expert.yml | 194 ++++++ .deepwork/experts/experts/learnings/.gitkeep | 0 .../experts/learnings/keep_experts_focused.md | 33 + .../experts/topics/discovery_descriptions.md | 83 +++ .../experts/topics/expert_design_patterns.md | 69 +++ CHANGELOG.md | 32 +- README.md | 10 +- pyproject.toml | 2 +- src/deepwork/cli/experts.py | 154 +++++ src/deepwork/cli/install.py | 63 ++ src/deepwork/cli/main.py | 3 + src/deepwork/cli/sync.py | 49 +- src/deepwork/core/experts_generator.py | 186 ++++++ src/deepwork/core/experts_parser.py | 480 +++++++++++++++ src/deepwork/schemas/expert_schema.py | 76 +++ .../experts/learnings/keep_experts_focused.md | 33 + .../templates/claude/agent-expert.md.jinja | 33 + tests/integration/test_experts_sync.py | 266 +++++++++ tests/unit/test_expert_schema.py | 216 +++++++ tests/unit/test_experts_cli.py | 300 ++++++++++ tests/unit/test_experts_generator.py | 256 ++++++++ tests/unit/test_experts_parser.py | 563 ++++++++++++++++++ uv.lock | 2 +- 24 files changed, 3307 insertions(+), 6 deletions(-) create mode 100644 .claude/agents/dwe_experts.md create mode 100644 .deepwork/experts/experts/expert.yml create mode 100644 .deepwork/experts/experts/learnings/.gitkeep create mode 100644 .deepwork/experts/experts/learnings/keep_experts_focused.md create mode 100644 .deepwork/experts/experts/topics/discovery_descriptions.md create mode 100644 .deepwork/experts/experts/topics/expert_design_patterns.md create mode 100644 src/deepwork/cli/experts.py create mode 100644 src/deepwork/core/experts_generator.py create mode 100644 src/deepwork/core/experts_parser.py create mode 100644 src/deepwork/schemas/expert_schema.py create mode 100644 src/deepwork/standard/experts/experts/learnings/keep_experts_focused.md create mode 100644 src/deepwork/templates/claude/agent-expert.md.jinja create mode 100644 tests/integration/test_experts_sync.py create mode 100644 tests/unit/test_expert_schema.py create mode 100644 tests/unit/test_experts_cli.py create mode 100644 tests/unit/test_experts_generator.py create mode 100644 tests/unit/test_experts_parser.py diff --git a/.claude/agents/dwe_experts.md b/.claude/agents/dwe_experts.md new file mode 100644 index 00000000..1a892b03 --- /dev/null +++ b/.claude/agents/dwe_experts.md @@ -0,0 +1,210 @@ +--- +name: experts-expert +description: "DeepWork experts system - creating, organizing, and evolving domain knowledge collections that auto-improve through topics and learnings." +--- + +# DeepWork Experts System + +You are an expert on the DeepWork experts system - the framework for building +auto-improving collections of domain knowledge. + +## Core Concepts + +**Experts** are structured knowledge repositories that grow smarter over time. +Each expert represents deep knowledge in a specific domain and consists of: + +- **Core expertise**: Foundational knowledge captured in expert.yml +- **Topics**: Detailed documentation on specific subjects +- **Learnings**: Hard-fought insights from real experiences + +## When to Create an Expert + +Create an expert when: +- You have recurring work in a specific domain +- Knowledge is scattered and needs consolidation +- You want to capture learnings that would otherwise be lost +- A domain has enough depth to warrant structured documentation + +Do NOT create an expert for: +- One-off tasks with no future relevance +- Domains too broad to be actionable (e.g., "Programming") +- Topics better served by external documentation + +## Expert Structure + +Experts live in `.deepwork/experts/[folder-name]/`: + +``` +.deepwork/experts/ +└── rails_activejob/ + ├── expert.yml + ├── topics/ + │ └── retry_handling.md + └── learnings/ + └── job_errors_not_going_to_sentry.md +``` + +The **expert name** derives from the folder name with spaces/underscores becoming +dashes: `rails_activejob` → `rails-activejob`. + +## Writing Good expert.yml + +The expert.yml has two key fields: + +### discovery_description +A concise description (1-3 sentences) that helps the system decide when to +invoke this expert. Be specific about the domain and capabilities. + +Good: "Ruby on Rails ActiveJob - background job processing, retries, queues, +and error handling in Rails applications." + +Bad: "Helps with Rails stuff." + +### full_expertise +The core knowledge payload (~5 pages max). Structure it as: + +1. **Identity statement**: "You are an expert on..." +2. **Core concepts**: Key ideas and mental models +3. **Common patterns**: Typical approaches and solutions +4. **Pitfalls to avoid**: Known gotchas and mistakes +5. **Decision frameworks**: How to choose between options + +Write in second person ("You should...") as this becomes agent instructions. + +## Writing Good Topics + +Topics are deep dives into specific subjects within the domain. + +### When to create a topic +- Subject needs more detail than fits in full_expertise +- You find yourself repeatedly explaining something +- A subject has enough nuance to warrant dedicated documentation + +### Topic file structure +```markdown +--- +name: Retry Handling +keywords: + - retry + - exponential backoff + - dead letter queue +last_updated: 2025-01-15 +--- + +[Detailed content here] +``` + +### Keyword guidelines +- Use topic-specific terms only +- Avoid broad domain terms (don't use "Rails" in a Rails expert's topics) +- Include synonyms and related terms users might search for +- 3-7 keywords is typical + +## Writing Good Learnings + +Learnings capture hard-fought insights from real experiences - like mini +retrospectives that prevent repeating mistakes. + +### When to create a learning +- You solved a non-obvious problem +- A debugging session revealed unexpected behavior +- You discovered something that contradicts common assumptions +- Future-you would benefit from this context + +### Learning file structure +```markdown +--- +name: Job errors not going to Sentry +last_updated: 2025-01-20 +summarized_result: | + Sentry changed their standard gem for hooking into jobs. + SolidQueue still worked but ActiveJobKubernetes did not. +--- + +## Context +What was happening and why it mattered... + +## Investigation +What you tried and what you discovered... + +## Resolution +How you fixed it and why that worked... + +## Key Takeaway +The generalizable insight for future reference... +``` + +### summarized_result guidelines +- 1-3 sentences capturing the key finding +- Should be useful even without reading the full body +- Focus on the "what" not the "how" + +## CLI Commands + +### Listing topics +```bash +deepwork topics --expert "expert-name" +``` +Returns markdown list with links, keywords, sorted by last_updated. + +### Listing learnings +```bash +deepwork learnings --expert "expert-name" +``` +Returns markdown list with links, summaries, sorted by last_updated. + +## How Experts Become Agents + +Running `deepwork sync` generates Claude agents in `.claude/agents/`: + +- Filename: `dwe_[expert-name].md` +- Agent name: `[expert-name]-expert` +- Body: full_expertise + dynamic topic/learning lists + +The dynamic embedding ensures agents always access current topics and learnings: +``` +$(deepwork topics --expert "expert-name") +$(deepwork learnings --expert "expert-name") +``` + +## Evolution Strategy + +Experts should evolve through use: + +1. **Start minimal**: Begin with core expertise, add topics/learnings as needed +2. **Capture immediately**: Document learnings right after solving problems +3. **Refine periodically**: Review and consolidate as patterns emerge +4. **Prune actively**: Remove outdated content, merge redundant topics + +## Naming Conventions + +### Expert folders +- Use lowercase with underscores: `rails_activejob`, `social_marketing` +- Be specific enough to be useful: `react_hooks` not just `react` +- Avoid redundant words: `activejob` not `activejob_expert` + +### Topic files +- Use lowercase with underscores: `retry_handling.md` +- Name describes the subject: `queue_configuration.md` +- Filenames are organizational only - the `name` frontmatter is displayed + +### Learning files +- Use lowercase with underscores: `job_errors_not_going_to_sentry.md` +- Name captures the problem or discovery +- Can be longer/descriptive since they're not referenced programmatically + +--- + +## Topics + +Detailed documentation on specific subjects within this domain. + +$(deepwork topics --expert "experts") + +--- + +## Learnings + +Hard-fought insights from real experiences. + +$(deepwork learnings --expert "experts") \ No newline at end of file diff --git a/.deepwork/experts/experts/expert.yml b/.deepwork/experts/experts/expert.yml new file mode 100644 index 00000000..94cced9c --- /dev/null +++ b/.deepwork/experts/experts/expert.yml @@ -0,0 +1,194 @@ +discovery_description: | + DeepWork experts system - creating, organizing, and evolving domain knowledge + collections that auto-improve through topics and learnings. + +full_expertise: | + # DeepWork Experts System + + You are an expert on the DeepWork experts system - the framework for building + auto-improving collections of domain knowledge. + + ## Core Concepts + + **Experts** are structured knowledge repositories that grow smarter over time. + Each expert represents deep knowledge in a specific domain and consists of: + + - **Core expertise**: Foundational knowledge captured in expert.yml + - **Topics**: Detailed documentation on specific subjects + - **Learnings**: Hard-fought insights from real experiences + + ## When to Create an Expert + + Create an expert when: + - You have recurring work in a specific domain + - Knowledge is scattered and needs consolidation + - You want to capture learnings that would otherwise be lost + - A domain has enough depth to warrant structured documentation + + Do NOT create an expert for: + - One-off tasks with no future relevance + - Domains too broad to be actionable (e.g., "Programming") + - Topics better served by external documentation + + ## Expert Structure + + Experts live in `.deepwork/experts/[folder-name]/`: + + ``` + .deepwork/experts/ + └── rails_activejob/ + ├── expert.yml + ├── topics/ + │ └── retry_handling.md + └── learnings/ + └── job_errors_not_going_to_sentry.md + ``` + + The **expert name** derives from the folder name with spaces/underscores becoming + dashes: `rails_activejob` → `rails-activejob`. + + ## Writing Good expert.yml + + The expert.yml has two key fields: + + ### discovery_description + A concise description (1-3 sentences) that helps the system decide when to + invoke this expert. Be specific about the domain and capabilities. + + Good: "Ruby on Rails ActiveJob - background job processing, retries, queues, + and error handling in Rails applications." + + Bad: "Helps with Rails stuff." + + ### full_expertise + The core knowledge payload (~5 pages max). Structure it as: + + 1. **Identity statement**: "You are an expert on..." + 2. **Core concepts**: Key ideas and mental models + 3. **Common patterns**: Typical approaches and solutions + 4. **Pitfalls to avoid**: Known gotchas and mistakes + 5. **Decision frameworks**: How to choose between options + + Write in second person ("You should...") as this becomes agent instructions. + + ## Writing Good Topics + + Topics are deep dives into specific subjects within the domain. + + ### When to create a topic + - Subject needs more detail than fits in full_expertise + - You find yourself repeatedly explaining something + - A subject has enough nuance to warrant dedicated documentation + + ### Topic file structure + ```markdown + --- + name: Retry Handling + keywords: + - retry + - exponential backoff + - dead letter queue + last_updated: 2025-01-15 + --- + + [Detailed content here] + ``` + + ### Keyword guidelines + - Use topic-specific terms only + - Avoid broad domain terms (don't use "Rails" in a Rails expert's topics) + - Include synonyms and related terms users might search for + - 3-7 keywords is typical + + ## Writing Good Learnings + + Learnings capture hard-fought insights from real experiences - like mini + retrospectives that prevent repeating mistakes. + + ### When to create a learning + - You solved a non-obvious problem + - A debugging session revealed unexpected behavior + - You discovered something that contradicts common assumptions + - Future-you would benefit from this context + + ### Learning file structure + ```markdown + --- + name: Job errors not going to Sentry + last_updated: 2025-01-20 + summarized_result: | + Sentry changed their standard gem for hooking into jobs. + SolidQueue still worked but ActiveJobKubernetes did not. + --- + + ## Context + What was happening and why it mattered... + + ## Investigation + What you tried and what you discovered... + + ## Resolution + How you fixed it and why that worked... + + ## Key Takeaway + The generalizable insight for future reference... + ``` + + ### summarized_result guidelines + - 1-3 sentences capturing the key finding + - Should be useful even without reading the full body + - Focus on the "what" not the "how" + + ## CLI Commands + + ### Listing topics + ```bash + deepwork topics --expert "expert-name" + ``` + Returns markdown list with links, keywords, sorted by last_updated. + + ### Listing learnings + ```bash + deepwork learnings --expert "expert-name" + ``` + Returns markdown list with links, summaries, sorted by last_updated. + + ## How Experts Become Agents + + Running `deepwork sync` generates Claude agents in `.claude/agents/`: + + - Filename: `dwe_[expert-name].md` + - Agent name: `[expert-name]-expert` + - Body: full_expertise + dynamic topic/learning lists + + The dynamic embedding ensures agents always access current topics and learnings: + ``` + $(deepwork topics --expert "expert-name") + $(deepwork learnings --expert "expert-name") + ``` + + ## Evolution Strategy + + Experts should evolve through use: + + 1. **Start minimal**: Begin with core expertise, add topics/learnings as needed + 2. **Capture immediately**: Document learnings right after solving problems + 3. **Refine periodically**: Review and consolidate as patterns emerge + 4. **Prune actively**: Remove outdated content, merge redundant topics + + ## Naming Conventions + + ### Expert folders + - Use lowercase with underscores: `rails_activejob`, `social_marketing` + - Be specific enough to be useful: `react_hooks` not just `react` + - Avoid redundant words: `activejob` not `activejob_expert` + + ### Topic files + - Use lowercase with underscores: `retry_handling.md` + - Name describes the subject: `queue_configuration.md` + - Filenames are organizational only - the `name` frontmatter is displayed + + ### Learning files + - Use lowercase with underscores: `job_errors_not_going_to_sentry.md` + - Name captures the problem or discovery + - Can be longer/descriptive since they're not referenced programmatically diff --git a/.deepwork/experts/experts/learnings/.gitkeep b/.deepwork/experts/experts/learnings/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.deepwork/experts/experts/learnings/keep_experts_focused.md b/.deepwork/experts/experts/learnings/keep_experts_focused.md new file mode 100644 index 00000000..b77186a0 --- /dev/null +++ b/.deepwork/experts/experts/learnings/keep_experts_focused.md @@ -0,0 +1,33 @@ +--- +name: Keep Experts Focused +last_updated: 2025-01-30 +summarized_result: | + Broad experts like "Rails" or "JavaScript" become too large and unfocused. + Better to create specific experts like "Rails ActiveJob" or "React Hooks". +--- + +## Context + +When initially designing the experts system, we considered creating broad, +comprehensive experts that would cover entire technology stacks. + +## Investigation + +Testing showed that broad experts: +- Generated overwhelming amounts of content +- Struggled to provide specific, actionable guidance +- Made it difficult to know which expert to invoke +- Led to duplication across multiple broad experts + +## Resolution + +Adopted a principle of focused experts with clear boundaries: +- Each expert covers a specific domain or technology subset +- The discovery_description clearly indicates scope +- Topics dive deep rather than wide +- Learnings capture domain-specific insights + +## Key Takeaway + +An expert should be narrow enough that you can articulate its scope in 1-2 +sentences. If you can't, it's probably too broad. diff --git a/.deepwork/experts/experts/topics/discovery_descriptions.md b/.deepwork/experts/experts/topics/discovery_descriptions.md new file mode 100644 index 00000000..f68112b9 --- /dev/null +++ b/.deepwork/experts/experts/topics/discovery_descriptions.md @@ -0,0 +1,83 @@ +--- +name: Writing Discovery Descriptions +keywords: + - discovery + - description + - routing + - selection +last_updated: 2025-01-30 +--- + +# Writing Effective Discovery Descriptions + +The `discovery_description` determines when your expert gets invoked. It's the +"elevator pitch" that helps the system route queries to the right expert. + +## Purpose + +Discovery descriptions are used by other parts of the system to decide: +- Whether to suggest this expert for a task +- Which expert to invoke when multiple could apply +- How to present the expert to users + +## Anatomy of a Good Description + +```yaml +discovery_description: | + Ruby on Rails ActiveJob - background job processing including + queue configuration, retry strategies, error handling, and + integration with queue backends like Sidekiq and SolidQueue. +``` + +Components: +1. **Domain identifier**: "Ruby on Rails ActiveJob" +2. **Core capability**: "background job processing" +3. **Specific coverage**: "queue configuration, retry strategies..." +4. **Boundaries**: "integration with queue backends like..." + +## Guidelines + +### Be Specific +Bad: "Helps with background jobs" +Good: "Rails ActiveJob background processing - queues, retries, error handling" + +### Include Key Terms +Include terms users would search for. If someone asks about "Sidekiq retries", +the description should contain those words. + +### Set Boundaries +Indicate what's in and out of scope. "...including X, Y, Z" signals coverage. + +### Keep It Scannable +1-3 sentences max. The system needs to quickly evaluate relevance. + +### Avoid Marketing Speak +Bad: "The ultimate guide to mastering background jobs" +Good: "ActiveJob configuration, error handling, and queue backend integration" + +## Examples + +### Too Vague +```yaml +discovery_description: Helps with Rails development +``` + +### Too Narrow +```yaml +discovery_description: How to configure exponential backoff in ActiveJob +``` + +### Just Right +```yaml +discovery_description: | + Rails ActiveJob expertise - background job processing, queue + configuration, retry strategies, error handling, and integration + with Sidekiq, SolidQueue, and other queue backends. +``` + +## Testing Your Description + +Ask yourself: +1. If I had this problem, would I find this expert? +2. Does it differentiate from similar experts? +3. Can I tell what's covered in 5 seconds? diff --git a/.deepwork/experts/experts/topics/expert_design_patterns.md b/.deepwork/experts/experts/topics/expert_design_patterns.md new file mode 100644 index 00000000..3ce13a61 --- /dev/null +++ b/.deepwork/experts/experts/topics/expert_design_patterns.md @@ -0,0 +1,69 @@ +--- +name: Expert Design Patterns +keywords: + - patterns + - structure + - organization + - best practices +last_updated: 2025-01-30 +--- + +# Expert Design Patterns + +Common patterns for structuring effective experts. + +## The Layered Knowledge Pattern + +Structure expertise from general to specific: + +1. **full_expertise**: Core concepts, decision frameworks, common patterns +2. **topics/**: Deep dives into specific subjects +3. **learnings/**: Concrete experiences and edge cases + +This mirrors how humans learn - start with foundations, then specialize. + +## The Problem-Solution Pattern + +For domains centered around solving problems: + +- **full_expertise**: Problem categories, diagnostic approaches, solution frameworks +- **topics/**: Specific problem types with detailed solutions +- **learnings/**: Real debugging sessions and unexpected fixes + +Works well for: troubleshooting guides, error handling, debugging domains. + +## The Reference Pattern + +For domains with lots of factual information: + +- **full_expertise**: Overview, when to use what, quick reference +- **topics/**: Detailed reference on specific APIs, configs, options +- **learnings/**: Gotchas and undocumented behaviors + +Works well for: API documentation, configuration guides, tool references. + +## The Process Pattern + +For domains with sequential workflows: + +- **full_expertise**: Overall process, decision points, success criteria +- **topics/**: Detailed steps for each phase +- **learnings/**: Process failures and improvements + +Works well for: deployment procedures, review processes, onboarding. + +## Anti-Patterns to Avoid + +### The Kitchen Sink +Cramming everything into full_expertise. If it's over 5 pages, split into topics. + +### The Empty Shell +Creating expert.yml with minimal content and empty topics/learnings folders. +Start with meaningful content or don't create the expert yet. + +### The Stale Expert +Never updating after initial creation. Set a reminder to review quarterly. + +### The Duplicate Expert +Creating overlapping experts. Better to have one comprehensive expert than +several fragmented ones. diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f9c4dc4..4277c9dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Meta-skill template renders concurrent steps as "Background Task 1/2/3" with clear instructions - Added `get_step_entry_position_in_workflow()` and `get_concurrent_step_info()` methods to JobDefinition - Full backward compatibility: existing workflows with simple step arrays continue to work + +### Changed + +### Fixed + +### Removed + +## [0.6.0] - 2026-01-30 + +### Added +- **Experts system** for auto-improving collections of domain knowledge + - New `expert.yml` format with `discovery_description` and `full_expertise` fields + - Topics: Detailed documentation in `topics/*.md` with name, keywords, and last_updated frontmatter + - Learnings: Experience-based insights in `learnings/*.md` with summarized_result frontmatter + - Experts live in `.deepwork/experts/[folder-name]/` directory +- New CLI commands for experts: + - `deepwork topics --expert "name"` - Lists topics as markdown, sorted by most recently updated + - `deepwork learnings --expert "name"` - Lists learnings as markdown with summarized results +- Expert agent generation during `deepwork sync`: + - Generates Claude agents in `.claude/agents/dwe_[expert-name].md` + - Agent name format: `[expert-name]-expert` + - Uses dynamic command embedding (`$(deepwork topics ...)`) for always-current content +- Standard "experts" expert shipped with DeepWork documenting the experts system itself + - Includes topics on design patterns and discovery descriptions + - Includes learning on keeping experts focused +- Expert installation during `deepwork install`: + - Standard experts from `src/deepwork/standard/experts/` copied to `.deepwork/experts/` + - Creates `.deepwork/experts/` directory during installation +- Comprehensive test suite for experts (99 new tests) - Agent delegation field for job.yml steps - New `agent` field on steps allows specifying an agent type (e.g., `agent: general-purpose`) - When `agent` is set, generated Claude Code skills automatically include `context: fork` and `agent:` in frontmatter @@ -244,7 +273,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Initial version. -[Unreleased]: https://github.com/Unsupervisedcom/deepwork/compare/0.5.1...HEAD +[Unreleased]: https://github.com/Unsupervisedcom/deepwork/compare/0.6.0...HEAD +[0.6.0]: https://github.com/Unsupervisedcom/deepwork/releases/tag/0.6.0 [0.5.1]: https://github.com/Unsupervisedcom/deepwork/releases/tag/0.5.1 [0.5.0]: https://github.com/Unsupervisedcom/deepwork/releases/tag/0.5.0 [0.4.2]: https://github.com/anthropics/deepwork/compare/0.4.1...0.4.2 diff --git a/README.md b/README.md index 76a659de..66c51779 100644 --- a/README.md +++ b/README.md @@ -199,12 +199,18 @@ your-project/ ├── .deepwork/ │ ├── config.yml # Platform configuration │ ├── rules/ # Automated rules +│ ├── experts/ # Domain knowledge experts +│ │ └── expert_name/ +│ │ ├── expert.yml # Expert definition +│ │ ├── topics/ # Detailed topic documentation +│ │ └── learnings/ # Experience-based insights │ └── jobs/ # Job definitions │ └── job_name/ │ ├── job.yml # Job metadata │ └── steps/ # Step instructions -├── .claude/ # Generated Claude skills -│ └── skills/ +├── .claude/ # Generated Claude skills and agents +│ ├── skills/ +│ └── agents/ # Expert agents (dwe_*.md) └── deepwork-output/ # Job outputs (gitignored) ``` diff --git a/pyproject.toml b/pyproject.toml index c2bc3e4a..57d7de93 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "deepwork" -version = "0.5.1" +version = "0.6.0" description = "Framework for enabling AI agents to perform complex, multi-step work tasks" readme = "README.md" requires-python = ">=3.11" diff --git a/src/deepwork/cli/experts.py b/src/deepwork/cli/experts.py new file mode 100644 index 00000000..ad29510b --- /dev/null +++ b/src/deepwork/cli/experts.py @@ -0,0 +1,154 @@ +"""Expert commands for DeepWork CLI.""" + +from pathlib import Path + +import click +from rich.console import Console + +from deepwork.core.experts_parser import ( + ExpertParseError, + format_learnings_markdown, + format_topics_markdown, + parse_expert_definition, +) + +console = Console() + + +class ExpertNotFoundError(Exception): + """Exception raised when an expert is not found.""" + + pass + + +def _find_expert_dir(expert_name: str, project_path: Path) -> Path: + """ + Find the expert directory for a given expert name. + + The expert name uses dashes (e.g., "rails-activejob") but the folder + name may use underscores (e.g., "rails_activejob"). + + Args: + expert_name: Expert name (with dashes) + project_path: Project root directory + + Returns: + Path to expert directory + + Raises: + ExpertNotFoundError: If expert is not found + """ + experts_dir = project_path / ".deepwork" / "experts" + + if not experts_dir.exists(): + raise ExpertNotFoundError( + f"No experts directory found at {experts_dir}.\n" + "Run 'deepwork install' to set up the experts system." + ) + + # Convert expert name back to possible folder names + # rails-activejob -> rails_activejob, rails-activejob + possible_names = [ + expert_name.replace("-", "_"), # rails_activejob + expert_name, # rails-activejob (direct match) + ] + + for folder_name in possible_names: + expert_dir = experts_dir / folder_name + if expert_dir.exists() and (expert_dir / "expert.yml").exists(): + return expert_dir + + # List available experts for helpful error message + available_experts = [] + if experts_dir.exists(): + for subdir in experts_dir.iterdir(): + if subdir.is_dir() and (subdir / "expert.yml").exists(): + # Convert folder name to expert name (underscores to dashes) + name = subdir.name.replace("_", "-") + available_experts.append(name) + + if available_experts: + available_str = ", ".join(sorted(available_experts)) + raise ExpertNotFoundError( + f"Expert '{expert_name}' not found.\n" + f"Available experts: {available_str}" + ) + else: + raise ExpertNotFoundError( + f"Expert '{expert_name}' not found.\n" + "No experts have been defined yet." + ) + + +@click.command() +@click.option( + "--expert", + "-e", + required=True, + help="Expert name (e.g., 'rails-activejob')", +) +@click.option( + "--path", + type=click.Path(exists=True, file_okay=False, path_type=Path), + default=".", + help="Path to project directory (default: current directory)", +) +def topics(expert: str, path: Path) -> None: + """ + List topics for an expert. + + Returns a Markdown list of topics with names, file paths as links, + and keywords, sorted by most-recently-updated. + + Example: + deepwork topics --expert "rails-activejob" + """ + try: + expert_dir = _find_expert_dir(expert, path) + expert_def = parse_expert_definition(expert_dir) + output = format_topics_markdown(expert_def) + # Print raw output (no Rich formatting) for use in $(command) embedding + print(output) + except ExpertNotFoundError as e: + console.print(f"[red]Error:[/red] {e}") + raise click.Abort() from e + except ExpertParseError as e: + console.print(f"[red]Error parsing expert:[/red] {e}") + raise click.Abort() from e + + +@click.command() +@click.option( + "--expert", + "-e", + required=True, + help="Expert name (e.g., 'rails-activejob')", +) +@click.option( + "--path", + type=click.Path(exists=True, file_okay=False, path_type=Path), + default=".", + help="Path to project directory (default: current directory)", +) +def learnings(expert: str, path: Path) -> None: + """ + List learnings for an expert. + + Returns a Markdown list of learnings with names, file paths as links, + and summarized results, sorted by most-recently-updated. + + Example: + deepwork learnings --expert "rails-activejob" + """ + try: + expert_dir = _find_expert_dir(expert, path) + expert_def = parse_expert_definition(expert_dir) + output = format_learnings_markdown(expert_def) + # Print raw output (no Rich formatting) for use in $(command) embedding + print(output) + except ExpertNotFoundError as e: + console.print(f"[red]Error:[/red] {e}") + raise click.Abort() from e + except ExpertParseError as e: + console.print(f"[red]Error parsing expert:[/red] {e}") + raise click.Abort() from e diff --git a/src/deepwork/cli/install.py b/src/deepwork/cli/install.py index 19bec4f8..73a5b97b 100644 --- a/src/deepwork/cli/install.py +++ b/src/deepwork/cli/install.py @@ -102,6 +102,61 @@ def _inject_deepwork_rules(jobs_dir: Path, project_path: Path) -> None: _inject_standard_job("deepwork_rules", jobs_dir, project_path) +def _inject_standard_experts(experts_dir: Path, project_path: Path) -> int: + """ + Inject standard expert definitions into the project. + + Copies all experts from src/deepwork/standard/experts/ to .deepwork/experts/. + + Args: + experts_dir: Path to .deepwork/experts directory + project_path: Path to project root (for relative path display) + + Returns: + Number of experts installed + + Raises: + InstallError: If injection fails + """ + # Find the standard experts directory + standard_experts_dir = Path(__file__).parent.parent / "standard" / "experts" + + if not standard_experts_dir.exists(): + # No standard experts to install - this is OK + return 0 + + installed_count = 0 + + # Iterate through each expert in the standard experts directory + for expert_source_dir in standard_experts_dir.iterdir(): + if not expert_source_dir.is_dir(): + continue + + # Check if this is a valid expert (has expert.yml) + if not (expert_source_dir / "expert.yml").exists(): + continue + + expert_name = expert_source_dir.name + target_dir = experts_dir / expert_name + + try: + if target_dir.exists(): + # Remove existing if present (for reinstall/upgrade) + shutil.rmtree(target_dir) + + shutil.copytree(expert_source_dir, target_dir) + # Fix permissions - source may have restrictive permissions + fix_permissions(target_dir) + console.print( + f" [green]✓[/green] Installed expert: {expert_name} ({target_dir.relative_to(project_path)})" + ) + installed_count += 1 + except Exception as e: + raise InstallError(f"Failed to install expert {expert_name}: {e}") from e + + return installed_count + + def _create_deepwork_gitignore(deepwork_dir: Path) -> None: """ Create .gitignore file in .deepwork/ directory. @@ -346,9 +401,11 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None: deepwork_dir = project_path / ".deepwork" jobs_dir = deepwork_dir / "jobs" doc_specs_dir = deepwork_dir / "doc_specs" + experts_dir = deepwork_dir / "experts" ensure_dir(deepwork_dir) ensure_dir(jobs_dir) ensure_dir(doc_specs_dir) + ensure_dir(experts_dir) console.print(f" [green]✓[/green] Created {deepwork_dir.relative_to(project_path)}/") # Step 3b: Inject standard jobs (core job definitions) @@ -356,6 +413,12 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None: _inject_deepwork_jobs(jobs_dir, project_path) _inject_deepwork_rules(jobs_dir, project_path) + # Step 3b-2: Inject standard experts + console.print("[yellow]→[/yellow] Installing standard experts...") + experts_count = _inject_standard_experts(experts_dir, project_path) + if experts_count == 0: + console.print(" [dim]•[/dim] No standard experts to install") + # Step 3c: Create .gitignore for temporary files _create_deepwork_gitignore(deepwork_dir) console.print(" [green]✓[/green] Created .deepwork/.gitignore") diff --git a/src/deepwork/cli/main.py b/src/deepwork/cli/main.py index b503ea9a..b5541455 100644 --- a/src/deepwork/cli/main.py +++ b/src/deepwork/cli/main.py @@ -14,6 +14,7 @@ def cli() -> None: # Import commands +from deepwork.cli.experts import learnings, topics # noqa: E402 from deepwork.cli.hook import hook # noqa: E402 from deepwork.cli.install import install # noqa: E402 from deepwork.cli.rules import rules # noqa: E402 @@ -23,6 +24,8 @@ def cli() -> None: cli.add_command(sync) cli.add_command(hook) cli.add_command(rules) +cli.add_command(topics) +cli.add_command(learnings) if __name__ == "__main__": diff --git a/src/deepwork/cli/sync.py b/src/deepwork/cli/sync.py index 03c47a30..e3795156 100644 --- a/src/deepwork/cli/sync.py +++ b/src/deepwork/cli/sync.py @@ -7,6 +7,12 @@ from rich.table import Table from deepwork.core.adapters import AgentAdapter +from deepwork.core.experts_generator import ExpertGenerator +from deepwork.core.experts_parser import ( + ExpertParseError, + discover_experts, + parse_expert_definition, +) from deepwork.core.generator import SkillGenerator from deepwork.core.hooks_syncer import collect_job_hooks, sync_hooks_to_platform from deepwork.core.parser import parse_job_definition @@ -114,9 +120,33 @@ def sync_skills(project_path: Path) -> None: if job_hooks_list: console.print(f"[yellow]→[/yellow] Found {len(job_hooks_list)} job(s) with hooks") + # Discover and parse experts + experts_dir = deepwork_dir / "experts" + expert_dirs = discover_experts(experts_dir) + console.print(f"[yellow]→[/yellow] Found {len(expert_dirs)} expert(s) to sync") + + experts = [] + failed_experts: list[tuple[str, str]] = [] + for expert_dir in expert_dirs: + try: + expert_def = parse_expert_definition(expert_dir) + experts.append(expert_def) + console.print(f" [green]✓[/green] Loaded {expert_def.name}") + except ExpertParseError as e: + console.print(f" [red]✗[/red] Failed to load {expert_dir.name}: {e}") + failed_experts.append((expert_dir.name, str(e))) + + # Warn but don't fail for expert parsing errors (experts are optional) + if failed_experts: + console.print() + console.print("[yellow]Warning: Some experts failed to parse:[/yellow]") + for expert_name, error in failed_experts: + console.print(f" • {expert_name}: {error}") + # Sync each platform generator = SkillGenerator() - stats = {"platforms": 0, "skills": 0, "hooks": 0} + expert_generator = ExpertGenerator() + stats = {"platforms": 0, "skills": 0, "hooks": 0, "agents": 0} for platform_name in platforms: try: @@ -149,6 +179,21 @@ def sync_skills(project_path: Path) -> None: except Exception as e: console.print(f" [red]✗[/red] Failed for {job.name}: {e}") + # Generate expert agents (only for Claude currently - agents live in .claude/agents/) + if experts and adapter.name == "claude": + console.print(" [dim]•[/dim] Generating expert agents...") + for expert in experts: + try: + agent_path = expert_generator.generate_expert_agent( + expert, adapter, platform_dir + ) + stats["agents"] += 1 + console.print( + f" [green]✓[/green] {expert.name} ({agent_path.name})" + ) + except Exception as e: + console.print(f" [red]✗[/red] Failed for {expert.name}: {e}") + # Sync hooks to platform settings if job_hooks_list: console.print(" [dim]•[/dim] Syncing hooks...") @@ -195,6 +240,8 @@ def sync_skills(project_path: Path) -> None: table.add_row("Platforms synced", str(stats["platforms"])) table.add_row("Total skills", str(stats["skills"])) + if stats["agents"] > 0: + table.add_row("Expert agents", str(stats["agents"])) if stats["hooks"] > 0: table.add_row("Hooks synced", str(stats["hooks"])) diff --git a/src/deepwork/core/experts_generator.py b/src/deepwork/core/experts_generator.py new file mode 100644 index 00000000..023e57c1 --- /dev/null +++ b/src/deepwork/core/experts_generator.py @@ -0,0 +1,186 @@ +"""Expert agent generator using Jinja2 templates.""" + +from pathlib import Path + +from jinja2 import Environment, FileSystemLoader, TemplateNotFound + +from deepwork.core.adapters import AgentAdapter +from deepwork.core.experts_parser import ExpertDefinition +from deepwork.utils.fs import safe_write + + +class ExpertGeneratorError(Exception): + """Exception raised for expert agent generation errors.""" + + pass + + +class ExpertGenerator: + """Generates agent files from expert definitions.""" + + # Template filename for expert agents + EXPERT_AGENT_TEMPLATE = "agent-expert.md.jinja" + + def __init__(self, templates_dir: Path | str | None = None): + """ + Initialize generator. + + Args: + templates_dir: Path to templates directory + (defaults to package templates directory) + """ + if templates_dir is None: + templates_dir = Path(__file__).parent.parent / "templates" + + self.templates_dir = Path(templates_dir) + + if not self.templates_dir.exists(): + raise ExpertGeneratorError(f"Templates directory not found: {self.templates_dir}") + + def _get_jinja_env(self, adapter: AgentAdapter) -> Environment: + """ + Get Jinja2 environment for an adapter. + + Args: + adapter: Agent adapter + + Returns: + Jinja2 Environment + """ + platform_templates_dir = adapter.get_template_dir(self.templates_dir) + if not platform_templates_dir.exists(): + raise ExpertGeneratorError( + f"Templates for platform '{adapter.name}' not found at {platform_templates_dir}" + ) + + return Environment( + loader=FileSystemLoader(platform_templates_dir), + trim_blocks=True, + lstrip_blocks=True, + ) + + def _build_expert_context(self, expert: ExpertDefinition) -> dict: + """ + Build template context for an expert. + + Args: + expert: Expert definition + + Returns: + Template context dictionary + """ + return { + "expert_name": expert.name, + "discovery_description": expert.discovery_description, + "full_expertise": expert.full_expertise, + "topics_count": len(expert.topics), + "learnings_count": len(expert.learnings), + } + + def get_agent_filename(self, expert_name: str) -> str: + """ + Get the filename for an expert agent. + + Args: + expert_name: Name of the expert (e.g., "rails-activejob") + + Returns: + Agent filename (e.g., "dwe_rails-activejob.md") + """ + return f"dwe_{expert_name}.md" + + def get_agent_name(self, expert_name: str) -> str: + """ + Get the agent name field value for an expert. + + Args: + expert_name: Name of the expert (e.g., "rails-activejob") + + Returns: + Agent name (e.g., "rails-activejob-expert") + """ + return f"{expert_name}-expert" + + def generate_expert_agent( + self, + expert: ExpertDefinition, + adapter: AgentAdapter, + output_dir: Path | str, + ) -> Path: + """ + Generate an agent file from an expert definition. + + Args: + expert: Expert definition + adapter: Agent adapter for the target platform + output_dir: Platform config directory (e.g., .claude/) + + Returns: + Path to generated agent file + + Raises: + ExpertGeneratorError: If generation fails + """ + output_dir = Path(output_dir) + + # Create agents subdirectory + agents_dir = output_dir / "agents" + agents_dir.mkdir(parents=True, exist_ok=True) + + # Build context + context = self._build_expert_context(expert) + + # Load and render template + env = self._get_jinja_env(adapter) + try: + template = env.get_template(self.EXPERT_AGENT_TEMPLATE) + except TemplateNotFound as e: + raise ExpertGeneratorError( + f"Expert agent template not found: {self.EXPERT_AGENT_TEMPLATE}" + ) from e + + try: + rendered = template.render(**context) + except Exception as e: + raise ExpertGeneratorError( + f"Expert agent template rendering failed for '{expert.name}': {e}" + ) from e + + # Write agent file + agent_filename = self.get_agent_filename(expert.name) + agent_path = agents_dir / agent_filename + + try: + safe_write(agent_path, rendered) + except Exception as e: + raise ExpertGeneratorError(f"Failed to write agent file: {e}") from e + + return agent_path + + def generate_all_expert_agents( + self, + experts: list[ExpertDefinition], + adapter: AgentAdapter, + output_dir: Path | str, + ) -> list[Path]: + """ + Generate agent files for all experts. + + Args: + experts: List of expert definitions + adapter: Agent adapter for the target platform + output_dir: Platform config directory (e.g., .claude/) + + Returns: + List of paths to generated agent files + + Raises: + ExpertGeneratorError: If generation fails for any expert + """ + agent_paths: list[Path] = [] + + for expert in experts: + agent_path = self.generate_expert_agent(expert, adapter, output_dir) + agent_paths.append(agent_path) + + return agent_paths diff --git a/src/deepwork/core/experts_parser.py b/src/deepwork/core/experts_parser.py new file mode 100644 index 00000000..5cb4ba8c --- /dev/null +++ b/src/deepwork/core/experts_parser.py @@ -0,0 +1,480 @@ +"""Expert definition parser.""" + +import re +from dataclasses import dataclass, field +from datetime import date +from pathlib import Path +from typing import Any + +from deepwork.schemas.expert_schema import ( + EXPERT_SCHEMA, + LEARNING_FRONTMATTER_SCHEMA, + TOPIC_FRONTMATTER_SCHEMA, +) +from deepwork.utils.validation import ValidationError, validate_against_schema +from deepwork.utils.yaml_utils import YAMLError, load_yaml, load_yaml_from_string + + +class ExpertParseError(Exception): + """Exception raised for expert parsing errors.""" + + pass + + +def _folder_name_to_expert_name(folder_name: str) -> str: + """ + Convert folder name to expert name. + + Spaces and underscores become dashes. + Example: rails_activejob -> rails-activejob + + Args: + folder_name: The folder name to convert + + Returns: + The expert name + """ + return folder_name.replace("_", "-").replace(" ", "-") + + +def _parse_frontmatter_markdown(content: str, file_type: str) -> tuple[dict[str, Any], str]: + """ + Parse frontmatter from markdown content. + + Expects format: + --- + key: value + --- + markdown body + + Args: + content: Full file content + file_type: Type of file for error messages (e.g., "topic", "learning") + + Returns: + Tuple of (frontmatter dict, body content) + + Raises: + ExpertParseError: If frontmatter is missing or invalid + """ + # Match frontmatter pattern: starts with ---, ends with --- + pattern = r"^---[ \t]*\n(.*?)^---[ \t]*\n?(.*)" + match = re.match(pattern, content.strip(), re.DOTALL | re.MULTILINE) + + if not match: + raise ExpertParseError( + f"{file_type.capitalize()} file must have YAML frontmatter (content between --- markers)" + ) + + frontmatter_yaml = match.group(1) + body = match.group(2).strip() if match.group(2) else "" + + try: + frontmatter = load_yaml_from_string(frontmatter_yaml) + except YAMLError as e: + raise ExpertParseError(f"Failed to parse {file_type} frontmatter: {e}") from e + + if frontmatter is None: + frontmatter = {} + + return frontmatter, body + + +def _normalize_frontmatter_for_validation(frontmatter: dict[str, Any]) -> dict[str, Any]: + """ + Normalize frontmatter data for schema validation. + + PyYAML auto-parses dates as datetime.date objects, but our schema + expects strings. This function converts them back to strings. + + Args: + frontmatter: Parsed frontmatter data + + Returns: + Normalized frontmatter with dates as strings + """ + result = frontmatter.copy() + if "last_updated" in result and isinstance(result["last_updated"], date): + result["last_updated"] = result["last_updated"].isoformat() + return result + + +def _parse_date(date_value: str | date | None) -> date | None: + """ + Parse a date value. + + Handles both string (YYYY-MM-DD) and datetime.date objects + (which PyYAML may auto-parse). + + Args: + date_value: Date string, date object, or None + + Returns: + Parsed date or None + """ + if date_value is None: + return None + if isinstance(date_value, date): + return date_value + try: + return date.fromisoformat(date_value) + except (ValueError, TypeError): + return None + + +@dataclass +class Topic: + """Represents a topic within an expert domain.""" + + name: str + keywords: list[str] = field(default_factory=list) + last_updated: date | None = None + body: str = "" + source_file: Path | None = None + + @property + def relative_path(self) -> str | None: + """Get relative path for display (topics/filename.md).""" + if self.source_file is None: + return None + return f"topics/{self.source_file.name}" + + @classmethod + def from_dict( + cls, data: dict[str, Any], body: str = "", source_file: Path | None = None + ) -> "Topic": + """Create Topic from dictionary.""" + return cls( + name=data["name"], + keywords=data.get("keywords", []), + last_updated=_parse_date(data.get("last_updated")), + body=body, + source_file=source_file, + ) + + +@dataclass +class Learning: + """Represents a learning within an expert domain.""" + + name: str + last_updated: date | None = None + summarized_result: str | None = None + body: str = "" + source_file: Path | None = None + + @property + def relative_path(self) -> str | None: + """Get relative path for display (learnings/filename.md).""" + if self.source_file is None: + return None + return f"learnings/{self.source_file.name}" + + @classmethod + def from_dict( + cls, data: dict[str, Any], body: str = "", source_file: Path | None = None + ) -> "Learning": + """Create Learning from dictionary.""" + return cls( + name=data["name"], + last_updated=_parse_date(data.get("last_updated")), + summarized_result=data.get("summarized_result"), + body=body, + source_file=source_file, + ) + + +@dataclass +class ExpertDefinition: + """Represents a complete expert definition.""" + + name: str # Derived from folder name + discovery_description: str + full_expertise: str + expert_dir: Path + topics: list[Topic] = field(default_factory=list) + learnings: list[Learning] = field(default_factory=list) + + def get_topics_sorted(self) -> list[Topic]: + """ + Get topics sorted by most-recently-updated. + + Topics without last_updated are sorted last. + """ + return sorted( + self.topics, + key=lambda t: (t.last_updated is not None, t.last_updated), + reverse=True, + ) + + def get_learnings_sorted(self) -> list[Learning]: + """ + Get learnings sorted by most-recently-updated. + + Learnings without last_updated are sorted last. + """ + return sorted( + self.learnings, + key=lambda learning: (learning.last_updated is not None, learning.last_updated), + reverse=True, + ) + + @classmethod + def from_dict( + cls, + data: dict[str, Any], + expert_dir: Path, + topics: list[Topic] | None = None, + learnings: list[Learning] | None = None, + ) -> "ExpertDefinition": + """ + Create ExpertDefinition from dictionary. + + Args: + data: Parsed YAML data from expert.yml + expert_dir: Directory containing expert definition + topics: List of parsed topics + learnings: List of parsed learnings + + Returns: + ExpertDefinition instance + """ + name = _folder_name_to_expert_name(expert_dir.name) + return cls( + name=name, + discovery_description=data["discovery_description"].strip(), + full_expertise=data["full_expertise"].strip(), + expert_dir=expert_dir, + topics=topics or [], + learnings=learnings or [], + ) + + +def parse_topic_file(filepath: Path | str) -> Topic: + """ + Parse a topic file. + + Args: + filepath: Path to the topic file (markdown with YAML frontmatter) + + Returns: + Parsed Topic + + Raises: + ExpertParseError: If parsing fails or validation errors occur + """ + filepath = Path(filepath) + + if not filepath.exists(): + raise ExpertParseError(f"Topic file does not exist: {filepath}") + + if not filepath.is_file(): + raise ExpertParseError(f"Topic path is not a file: {filepath}") + + try: + content = filepath.read_text(encoding="utf-8") + except Exception as e: + raise ExpertParseError(f"Failed to read topic file: {e}") from e + + frontmatter, body = _parse_frontmatter_markdown(content, "topic") + + try: + # Normalize frontmatter for validation (converts date objects to strings) + normalized = _normalize_frontmatter_for_validation(frontmatter) + validate_against_schema(normalized, TOPIC_FRONTMATTER_SCHEMA) + except ValidationError as e: + raise ExpertParseError(f"Topic validation failed in {filepath.name}: {e}") from e + + return Topic.from_dict(frontmatter, body, filepath) + + +def parse_learning_file(filepath: Path | str) -> Learning: + """ + Parse a learning file. + + Args: + filepath: Path to the learning file (markdown with YAML frontmatter) + + Returns: + Parsed Learning + + Raises: + ExpertParseError: If parsing fails or validation errors occur + """ + filepath = Path(filepath) + + if not filepath.exists(): + raise ExpertParseError(f"Learning file does not exist: {filepath}") + + if not filepath.is_file(): + raise ExpertParseError(f"Learning path is not a file: {filepath}") + + try: + content = filepath.read_text(encoding="utf-8") + except Exception as e: + raise ExpertParseError(f"Failed to read learning file: {e}") from e + + frontmatter, body = _parse_frontmatter_markdown(content, "learning") + + try: + # Normalize frontmatter for validation (converts date objects to strings) + normalized = _normalize_frontmatter_for_validation(frontmatter) + validate_against_schema(normalized, LEARNING_FRONTMATTER_SCHEMA) + except ValidationError as e: + raise ExpertParseError(f"Learning validation failed in {filepath.name}: {e}") from e + + return Learning.from_dict(frontmatter, body, filepath) + + +def parse_expert_definition(expert_dir: Path | str) -> ExpertDefinition: + """ + Parse expert definition from directory. + + Args: + expert_dir: Directory containing expert.yml + + Returns: + Parsed ExpertDefinition + + Raises: + ExpertParseError: If parsing fails or validation errors occur + """ + expert_dir_path = Path(expert_dir) + + if not expert_dir_path.exists(): + raise ExpertParseError(f"Expert directory does not exist: {expert_dir_path}") + + if not expert_dir_path.is_dir(): + raise ExpertParseError(f"Expert path is not a directory: {expert_dir_path}") + + expert_file = expert_dir_path / "expert.yml" + if not expert_file.exists(): + raise ExpertParseError(f"expert.yml not found in {expert_dir_path}") + + # Load YAML + try: + expert_data = load_yaml(expert_file) + except YAMLError as e: + raise ExpertParseError(f"Failed to load expert.yml: {e}") from e + + if expert_data is None: + raise ExpertParseError("expert.yml is empty") + + # Validate against schema + try: + validate_against_schema(expert_data, EXPERT_SCHEMA) + except ValidationError as e: + raise ExpertParseError(f"Expert definition validation failed: {e}") from e + + # Parse topics + topics: list[Topic] = [] + topics_dir = expert_dir_path / "topics" + if topics_dir.exists() and topics_dir.is_dir(): + for topic_file in topics_dir.glob("*.md"): + try: + topic = parse_topic_file(topic_file) + topics.append(topic) + except ExpertParseError: + raise + + # Parse learnings + learnings: list[Learning] = [] + learnings_dir = expert_dir_path / "learnings" + if learnings_dir.exists() and learnings_dir.is_dir(): + for learning_file in learnings_dir.glob("*.md"): + try: + learning = parse_learning_file(learning_file) + learnings.append(learning) + except ExpertParseError: + raise + + return ExpertDefinition.from_dict(expert_data, expert_dir_path, topics, learnings) + + +def discover_experts(experts_dir: Path | str) -> list[Path]: + """ + Discover all expert directories in a given directory. + + An expert directory is one that contains an expert.yml file. + + Args: + experts_dir: Directory containing expert subdirectories + + Returns: + List of paths to expert directories + """ + experts_dir_path = Path(experts_dir) + + if not experts_dir_path.exists(): + return [] + + if not experts_dir_path.is_dir(): + return [] + + expert_dirs: list[Path] = [] + for subdir in experts_dir_path.iterdir(): + if subdir.is_dir() and (subdir / "expert.yml").exists(): + expert_dirs.append(subdir) + + return expert_dirs + + +def format_topics_markdown(expert: ExpertDefinition) -> str: + """ + Format topics as a markdown list for CLI output. + + Returns name and relative file path as a markdown link, + followed by keywords, sorted by most-recently-updated. + + Args: + expert: Expert definition + + Returns: + Markdown formatted list of topics + """ + topics = expert.get_topics_sorted() + if not topics: + return "_No topics yet._" + + lines = [] + for topic in topics: + # Format: [Topic Name](topics/filename.md) + rel_path = topic.relative_path or "topics/unknown.md" + line = f"- [{topic.name}]({rel_path})" + if topic.keywords: + line += f"\n Keywords: {', '.join(topic.keywords)}" + lines.append(line) + + return "\n".join(lines) + + +def format_learnings_markdown(expert: ExpertDefinition) -> str: + """ + Format learnings as a markdown list for CLI output. + + Returns name and relative file path as a markdown link, + followed by the summarized result, sorted by most-recently-updated. + + Args: + expert: Expert definition + + Returns: + Markdown formatted list of learnings + """ + learnings = expert.get_learnings_sorted() + if not learnings: + return "_No learnings yet._" + + lines = [] + for learning in learnings: + # Format: [Learning Name](learnings/filename.md) + rel_path = learning.relative_path or "learnings/unknown.md" + line = f"- [{learning.name}]({rel_path})" + if learning.summarized_result: + # Add indented summary + summary_lines = learning.summarized_result.strip().split("\n") + for summary_line in summary_lines: + line += f"\n {summary_line}" + lines.append(line) + + return "\n".join(lines) diff --git a/src/deepwork/schemas/expert_schema.py b/src/deepwork/schemas/expert_schema.py new file mode 100644 index 00000000..df4fd379 --- /dev/null +++ b/src/deepwork/schemas/expert_schema.py @@ -0,0 +1,76 @@ +"""JSON Schema definitions for expert definitions.""" + +from typing import Any + +# JSON Schema for expert.yml files +EXPERT_SCHEMA: dict[str, Any] = { + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": ["discovery_description", "full_expertise"], + "properties": { + "discovery_description": { + "type": "string", + "minLength": 1, + "description": "Short description used to decide whether to invoke this expert. Keep concise and specific.", + }, + "full_expertise": { + "type": "string", + "minLength": 1, + "description": "Complete current knowledge of this domain (~5 pages max). This is included in the generated agent.", + }, + }, + "additionalProperties": False, +} + +# JSON Schema for topic frontmatter +TOPIC_FRONTMATTER_SCHEMA: dict[str, Any] = { + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "Human-readable topic name (e.g., 'Retry Handling')", + }, + "keywords": { + "type": "array", + "description": "Topic-specific keywords (avoid broad terms like the expert domain)", + "items": { + "type": "string", + "minLength": 1, + }, + }, + "last_updated": { + "type": "string", + "pattern": r"^\d{4}-\d{2}-\d{2}$", + "description": "Date stamp in YYYY-MM-DD format", + }, + }, + "additionalProperties": False, +} + +# JSON Schema for learning frontmatter +LEARNING_FRONTMATTER_SCHEMA: dict[str, Any] = { + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "Human-readable learning name (e.g., 'Job errors not going to Sentry')", + }, + "last_updated": { + "type": "string", + "pattern": r"^\d{4}-\d{2}-\d{2}$", + "description": "Date stamp in YYYY-MM-DD format", + }, + "summarized_result": { + "type": "string", + "minLength": 1, + "description": "Brief summary of the key finding (1-3 sentences)", + }, + }, + "additionalProperties": False, +} diff --git a/src/deepwork/standard/experts/experts/learnings/keep_experts_focused.md b/src/deepwork/standard/experts/experts/learnings/keep_experts_focused.md new file mode 100644 index 00000000..b77186a0 --- /dev/null +++ b/src/deepwork/standard/experts/experts/learnings/keep_experts_focused.md @@ -0,0 +1,33 @@ +--- +name: Keep Experts Focused +last_updated: 2025-01-30 +summarized_result: | + Broad experts like "Rails" or "JavaScript" become too large and unfocused. + Better to create specific experts like "Rails ActiveJob" or "React Hooks". +--- + +## Context + +When initially designing the experts system, we considered creating broad, +comprehensive experts that would cover entire technology stacks. + +## Investigation + +Testing showed that broad experts: +- Generated overwhelming amounts of content +- Struggled to provide specific, actionable guidance +- Made it difficult to know which expert to invoke +- Led to duplication across multiple broad experts + +## Resolution + +Adopted a principle of focused experts with clear boundaries: +- Each expert covers a specific domain or technology subset +- The discovery_description clearly indicates scope +- Topics dive deep rather than wide +- Learnings capture domain-specific insights + +## Key Takeaway + +An expert should be narrow enough that you can articulate its scope in 1-2 +sentences. If you can't, it's probably too broad. diff --git a/src/deepwork/templates/claude/agent-expert.md.jinja b/src/deepwork/templates/claude/agent-expert.md.jinja new file mode 100644 index 00000000..b7e0599d --- /dev/null +++ b/src/deepwork/templates/claude/agent-expert.md.jinja @@ -0,0 +1,33 @@ +{# +Template: agent-expert.md.jinja +Purpose: Generates an expert agent file for Claude Code + +Template Variables: + - expert_name: string - Expert identifier (e.g., "rails-activejob") + - discovery_description: string - Short description for expert discovery + - full_expertise: string - Complete expertise knowledge payload + - topics_count: int - Number of topics in this expert + - learnings_count: int - Number of learnings in this expert +#} +--- +name: {{ expert_name }}-expert +description: "{{ discovery_description | replace('"', '\\"') | replace('\n', ' ') | truncate(200) }}" +--- + +{{ full_expertise }} + +--- + +## Topics + +Detailed documentation on specific subjects within this domain. + +$(deepwork topics --expert "{{ expert_name }}") + +--- + +## Learnings + +Hard-fought insights from real experiences. + +$(deepwork learnings --expert "{{ expert_name }}") diff --git a/tests/integration/test_experts_sync.py b/tests/integration/test_experts_sync.py new file mode 100644 index 00000000..c829d4c4 --- /dev/null +++ b/tests/integration/test_experts_sync.py @@ -0,0 +1,266 @@ +"""Integration tests for expert sync functionality.""" + +from pathlib import Path + +import pytest + +from deepwork.cli.sync import sync_skills +from deepwork.utils.yaml_utils import save_yaml + + +@pytest.fixture +def project_with_experts(tmp_path: Path) -> Path: + """Create a minimal project with experts for sync testing.""" + # Create .deepwork directory structure + deepwork_dir = tmp_path / ".deepwork" + deepwork_dir.mkdir() + + # Create config.yml + config = {"version": "0.1.0", "platforms": ["claude"]} + save_yaml(deepwork_dir / "config.yml", config) + + # Create jobs directory (empty - no jobs to sync) + jobs_dir = deepwork_dir / "jobs" + jobs_dir.mkdir() + + # Create experts directory with an expert + experts_dir = deepwork_dir / "experts" + experts_dir.mkdir() + + expert_dir = experts_dir / "test_expert" + expert_dir.mkdir() + + # Create expert.yml + (expert_dir / "expert.yml").write_text( + """discovery_description: | + Test expert for integration testing + +full_expertise: | + # Test Expert + + You are an expert on testing integrations. + + ## Key Concepts + + - Integration testing + - End-to-end testing +""" + ) + + # Create topics + topics_dir = expert_dir / "topics" + topics_dir.mkdir() + (topics_dir / "basics.md").write_text( + """--- +name: Testing Basics +keywords: + - basics + - fundamentals +last_updated: 2025-01-30 +--- + +Content about testing basics. +""" + ) + + # Create learnings + learnings_dir = expert_dir / "learnings" + learnings_dir.mkdir() + (learnings_dir / "discovery.md").write_text( + """--- +name: Important Discovery +last_updated: 2025-01-20 +summarized_result: | + Found that integration tests should be isolated. +--- + +Details of the discovery. +""" + ) + + # Create .claude directory + claude_dir = tmp_path / ".claude" + claude_dir.mkdir() + + return tmp_path + + +class TestExpertSync: + """Tests for expert sync functionality.""" + + def test_sync_creates_expert_agent(self, project_with_experts: Path) -> None: + """Test that sync creates expert agent files.""" + # Run sync + sync_skills(project_with_experts) + + # Check that agent was created + agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" + assert agent_file.exists(), f"Expected agent file at {agent_file}" + + def test_sync_agent_has_correct_name(self, project_with_experts: Path) -> None: + """Test that generated agent has correct name field.""" + sync_skills(project_with_experts) + + agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" + content = agent_file.read_text() + + assert "name: test-expert-expert" in content + + def test_sync_agent_has_description(self, project_with_experts: Path) -> None: + """Test that generated agent has description from discovery_description.""" + sync_skills(project_with_experts) + + agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" + content = agent_file.read_text() + + assert "integration testing" in content.lower() + + def test_sync_agent_has_full_expertise(self, project_with_experts: Path) -> None: + """Test that generated agent includes full_expertise content.""" + sync_skills(project_with_experts) + + agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" + content = agent_file.read_text() + + assert "expert on testing integrations" in content + assert "Key Concepts" in content + + def test_sync_agent_has_dynamic_topics_command(self, project_with_experts: Path) -> None: + """Test that generated agent includes dynamic topics command embedding.""" + sync_skills(project_with_experts) + + agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" + content = agent_file.read_text() + + assert '$(deepwork topics --expert "test-expert")' in content + + def test_sync_agent_has_dynamic_learnings_command(self, project_with_experts: Path) -> None: + """Test that generated agent includes dynamic learnings command embedding.""" + sync_skills(project_with_experts) + + agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" + content = agent_file.read_text() + + assert '$(deepwork learnings --expert "test-expert")' in content + + +class TestExpertSyncMultiple: + """Tests for syncing multiple experts.""" + + def test_sync_multiple_experts(self, tmp_path: Path) -> None: + """Test syncing multiple experts creates multiple agent files.""" + # Create project structure + deepwork_dir = tmp_path / ".deepwork" + deepwork_dir.mkdir() + save_yaml(deepwork_dir / "config.yml", {"version": "0.1.0", "platforms": ["claude"]}) + (deepwork_dir / "jobs").mkdir() + + experts_dir = deepwork_dir / "experts" + experts_dir.mkdir() + + # Create multiple experts + for name in ["expert_a", "expert_b", "expert_c"]: + expert_dir = experts_dir / name + expert_dir.mkdir() + (expert_dir / "expert.yml").write_text( + f"discovery_description: Expert {name}\nfull_expertise: Content for {name}." + ) + + (tmp_path / ".claude").mkdir() + + # Run sync + sync_skills(tmp_path) + + # Check all agents were created + agents_dir = tmp_path / ".claude" / "agents" + assert (agents_dir / "dwe_expert-a.md").exists() + assert (agents_dir / "dwe_expert-b.md").exists() + assert (agents_dir / "dwe_expert-c.md").exists() + + +class TestExpertSyncNoExperts: + """Tests for syncing when no experts exist.""" + + def test_sync_no_experts_directory(self, tmp_path: Path) -> None: + """Test sync works when no experts directory exists.""" + # Create minimal project without experts + deepwork_dir = tmp_path / ".deepwork" + deepwork_dir.mkdir() + save_yaml(deepwork_dir / "config.yml", {"version": "0.1.0", "platforms": ["claude"]}) + (deepwork_dir / "jobs").mkdir() + (tmp_path / ".claude").mkdir() + + # Should not raise + sync_skills(tmp_path) + + # Agents directory may or may not exist, but should have no agent files + agents_dir = tmp_path / ".claude" / "agents" + if agents_dir.exists(): + agent_files = list(agents_dir.glob("dwe_*.md")) + assert len(agent_files) == 0 + + def test_sync_empty_experts_directory(self, tmp_path: Path) -> None: + """Test sync works when experts directory is empty.""" + # Create project with empty experts directory + deepwork_dir = tmp_path / ".deepwork" + deepwork_dir.mkdir() + save_yaml(deepwork_dir / "config.yml", {"version": "0.1.0", "platforms": ["claude"]}) + (deepwork_dir / "jobs").mkdir() + (deepwork_dir / "experts").mkdir() # Empty experts dir + (tmp_path / ".claude").mkdir() + + # Should not raise + sync_skills(tmp_path) + + +class TestExpertSyncWithJobs: + """Tests for syncing experts alongside jobs.""" + + def test_sync_experts_and_jobs_together(self, tmp_path: Path) -> None: + """Test that sync handles both experts and jobs.""" + # Create project structure + deepwork_dir = tmp_path / ".deepwork" + deepwork_dir.mkdir() + save_yaml(deepwork_dir / "config.yml", {"version": "0.1.0", "platforms": ["claude"]}) + + # Create a job + job_dir = deepwork_dir / "jobs" / "test_job" + job_dir.mkdir(parents=True) + (job_dir / "job.yml").write_text( + """name: test_job +version: 1.0.0 +summary: A test job +steps: + - id: step_one + name: Step One + description: First step + instructions_file: steps/step_one.md + outputs: + - output.md +""" + ) + steps_dir = job_dir / "steps" + steps_dir.mkdir() + (steps_dir / "step_one.md").write_text("Do the first step.") + + # Create an expert + expert_dir = deepwork_dir / "experts" / "test_expert" + expert_dir.mkdir(parents=True) + (expert_dir / "expert.yml").write_text( + "discovery_description: Test expert\nfull_expertise: Expert content." + ) + + (tmp_path / ".claude").mkdir() + + # Run sync + sync_skills(tmp_path) + + # Check both job skills and expert agents were created + skills_dir = tmp_path / ".claude" / "skills" + assert skills_dir.exists() + # Job should have created skills + assert any(skills_dir.iterdir()) + + agents_dir = tmp_path / ".claude" / "agents" + assert agents_dir.exists() + assert (agents_dir / "dwe_test-expert.md").exists() diff --git a/tests/unit/test_expert_schema.py b/tests/unit/test_expert_schema.py new file mode 100644 index 00000000..506b888c --- /dev/null +++ b/tests/unit/test_expert_schema.py @@ -0,0 +1,216 @@ +"""Tests for expert schema validation.""" + +import pytest + +from deepwork.schemas.expert_schema import ( + EXPERT_SCHEMA, + LEARNING_FRONTMATTER_SCHEMA, + TOPIC_FRONTMATTER_SCHEMA, +) +from deepwork.utils.validation import ValidationError, validate_against_schema + + +class TestExpertSchema: + """Tests for expert.yml schema validation.""" + + def test_valid_minimal_expert(self) -> None: + """Test valid minimal expert definition.""" + data = { + "discovery_description": "Test expert for unit testing", + "full_expertise": "You are an expert on testing.", + } + # Should not raise + validate_against_schema(data, EXPERT_SCHEMA) + + def test_valid_multiline_expert(self) -> None: + """Test valid expert with multiline content.""" + data = { + "discovery_description": "Test expert for unit testing\nwith multiple lines", + "full_expertise": "# Test Expert\n\nYou are an expert on testing.\n\n## Topics\n\n- Testing basics\n- Advanced testing", + } + # Should not raise + validate_against_schema(data, EXPERT_SCHEMA) + + def test_missing_discovery_description(self) -> None: + """Test that missing discovery_description fails validation.""" + data = { + "full_expertise": "You are an expert on testing.", + } + with pytest.raises(ValidationError, match="discovery_description"): + validate_against_schema(data, EXPERT_SCHEMA) + + def test_missing_full_expertise(self) -> None: + """Test that missing full_expertise fails validation.""" + data = { + "discovery_description": "Test expert", + } + with pytest.raises(ValidationError, match="full_expertise"): + validate_against_schema(data, EXPERT_SCHEMA) + + def test_empty_discovery_description(self) -> None: + """Test that empty discovery_description fails validation.""" + data = { + "discovery_description": "", + "full_expertise": "You are an expert on testing.", + } + with pytest.raises(ValidationError): + validate_against_schema(data, EXPERT_SCHEMA) + + def test_empty_full_expertise(self) -> None: + """Test that empty full_expertise fails validation.""" + data = { + "discovery_description": "Test expert", + "full_expertise": "", + } + with pytest.raises(ValidationError): + validate_against_schema(data, EXPERT_SCHEMA) + + def test_additional_properties_not_allowed(self) -> None: + """Test that additional properties are not allowed.""" + data = { + "discovery_description": "Test expert", + "full_expertise": "You are an expert on testing.", + "extra_field": "not allowed", + } + with pytest.raises(ValidationError, match="extra_field"): + validate_against_schema(data, EXPERT_SCHEMA) + + +class TestTopicFrontmatterSchema: + """Tests for topic frontmatter schema validation.""" + + def test_valid_minimal_topic(self) -> None: + """Test valid minimal topic with just name.""" + data = {"name": "Test Topic"} + # Should not raise + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_valid_full_topic(self) -> None: + """Test valid topic with all fields.""" + data = { + "name": "Test Topic", + "keywords": ["testing", "unit test", "pytest"], + "last_updated": "2025-01-30", + } + # Should not raise + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_missing_name(self) -> None: + """Test that missing name fails validation.""" + data = { + "keywords": ["testing"], + } + with pytest.raises(ValidationError, match="name"): + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_empty_name(self) -> None: + """Test that empty name fails validation.""" + data = {"name": ""} + with pytest.raises(ValidationError): + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_invalid_date_format(self) -> None: + """Test that invalid date format fails validation.""" + data = { + "name": "Test Topic", + "last_updated": "January 30, 2025", + } + with pytest.raises(ValidationError, match="last_updated"): + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_valid_date_format(self) -> None: + """Test that valid YYYY-MM-DD date format passes.""" + data = { + "name": "Test Topic", + "last_updated": "2025-01-30", + } + # Should not raise + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_empty_keywords_list(self) -> None: + """Test that empty keywords list is allowed.""" + data = { + "name": "Test Topic", + "keywords": [], + } + # Should not raise + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + def test_additional_properties_not_allowed(self) -> None: + """Test that additional properties are not allowed.""" + data = { + "name": "Test Topic", + "extra": "not allowed", + } + with pytest.raises(ValidationError, match="extra"): + validate_against_schema(data, TOPIC_FRONTMATTER_SCHEMA) + + +class TestLearningFrontmatterSchema: + """Tests for learning frontmatter schema validation.""" + + def test_valid_minimal_learning(self) -> None: + """Test valid minimal learning with just name.""" + data = {"name": "Test Learning"} + # Should not raise + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_valid_full_learning(self) -> None: + """Test valid learning with all fields.""" + data = { + "name": "Test Learning", + "last_updated": "2025-01-30", + "summarized_result": "Discovered that X causes Y under Z conditions.", + } + # Should not raise + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_missing_name(self) -> None: + """Test that missing name fails validation.""" + data = { + "summarized_result": "Some finding", + } + with pytest.raises(ValidationError, match="name"): + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_empty_name(self) -> None: + """Test that empty name fails validation.""" + data = {"name": ""} + with pytest.raises(ValidationError): + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_empty_summarized_result(self) -> None: + """Test that empty summarized_result fails validation.""" + data = { + "name": "Test Learning", + "summarized_result": "", + } + with pytest.raises(ValidationError): + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_invalid_date_format(self) -> None: + """Test that invalid date format fails validation.""" + data = { + "name": "Test Learning", + "last_updated": "30-01-2025", + } + with pytest.raises(ValidationError, match="last_updated"): + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_multiline_summarized_result(self) -> None: + """Test that multiline summarized_result is allowed.""" + data = { + "name": "Test Learning", + "summarized_result": "First line\nSecond line\nThird line", + } + # Should not raise + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) + + def test_additional_properties_not_allowed(self) -> None: + """Test that additional properties are not allowed.""" + data = { + "name": "Test Learning", + "extra": "not allowed", + } + with pytest.raises(ValidationError, match="extra"): + validate_against_schema(data, LEARNING_FRONTMATTER_SCHEMA) diff --git a/tests/unit/test_experts_cli.py b/tests/unit/test_experts_cli.py new file mode 100644 index 00000000..a4603bff --- /dev/null +++ b/tests/unit/test_experts_cli.py @@ -0,0 +1,300 @@ +"""Tests for expert CLI commands.""" + +from pathlib import Path + +import pytest +from click.testing import CliRunner + +from deepwork.cli.experts import learnings, topics + + +@pytest.fixture +def runner() -> CliRunner: + """Create a Click test runner.""" + return CliRunner() + + +@pytest.fixture +def project_with_expert(tmp_path: Path) -> Path: + """Create a project with an expert.""" + # Create .deepwork/experts directory + experts_dir = tmp_path / ".deepwork" / "experts" + experts_dir.mkdir(parents=True) + + # Create an expert + expert_dir = experts_dir / "test_expert" + expert_dir.mkdir() + + # Create expert.yml + (expert_dir / "expert.yml").write_text( + """discovery_description: | + Test expert for CLI testing + +full_expertise: | + You are an expert on testing CLI commands. +""" + ) + + # Create topics directory with topics + topics_dir = expert_dir / "topics" + topics_dir.mkdir() + + (topics_dir / "basics.md").write_text( + """--- +name: Testing Basics +keywords: + - testing + - basics +last_updated: 2025-01-30 +--- + +Content about testing basics. +""" + ) + + (topics_dir / "advanced.md").write_text( + """--- +name: Advanced Testing +keywords: + - advanced + - mocking +last_updated: 2025-01-15 +--- + +Content about advanced testing. +""" + ) + + # Create learnings directory with learnings + learnings_dir = expert_dir / "learnings" + learnings_dir.mkdir() + + (learnings_dir / "discovery.md").write_text( + """--- +name: Important Discovery +last_updated: 2025-01-20 +summarized_result: | + Found that X causes Y under Z conditions. +--- + +Full details of the discovery. +""" + ) + + return tmp_path + + +class TestTopicsCommand: + """Tests for the topics command.""" + + def test_topics_command_help(self, runner: CliRunner) -> None: + """Test topics command shows help.""" + result = runner.invoke(topics, ["--help"]) + + assert result.exit_code == 0 + assert "List topics for an expert" in result.output + assert "--expert" in result.output + + def test_topics_command_requires_expert(self, runner: CliRunner) -> None: + """Test topics command requires --expert option.""" + result = runner.invoke(topics, []) + + assert result.exit_code != 0 + assert "Missing option" in result.output or "required" in result.output.lower() + + def test_topics_command_lists_topics( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test topics command lists topics for an expert.""" + result = runner.invoke( + topics, ["--expert", "test-expert", "--path", str(project_with_expert)] + ) + + assert result.exit_code == 0 + assert "Testing Basics" in result.output + assert "Advanced Testing" in result.output + assert "testing" in result.output # keyword + assert "advanced" in result.output # keyword + + def test_topics_command_markdown_format( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test topics command outputs markdown format.""" + result = runner.invoke( + topics, ["--expert", "test-expert", "--path", str(project_with_expert)] + ) + + assert result.exit_code == 0 + # Should contain markdown links + assert "[Testing Basics]" in result.output + assert "(topics/" in result.output + + def test_topics_command_sorted_by_date( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test topics are sorted by most recently updated.""" + result = runner.invoke( + topics, ["--expert", "test-expert", "--path", str(project_with_expert)] + ) + + assert result.exit_code == 0 + # Testing Basics (2025-01-30) should come before Advanced Testing (2025-01-15) + basics_pos = result.output.find("Testing Basics") + advanced_pos = result.output.find("Advanced Testing") + assert basics_pos < advanced_pos + + def test_topics_command_expert_not_found( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test topics command with nonexistent expert.""" + result = runner.invoke( + topics, ["--expert", "nonexistent", "--path", str(project_with_expert)] + ) + + assert result.exit_code != 0 + assert "not found" in result.output.lower() + + def test_topics_command_no_experts_dir(self, runner: CliRunner, tmp_path: Path) -> None: + """Test topics command when no experts directory exists.""" + result = runner.invoke(topics, ["--expert", "test", "--path", str(tmp_path)]) + + assert result.exit_code != 0 + assert "No experts directory" in result.output or "not found" in result.output.lower() + + def test_topics_command_no_topics(self, runner: CliRunner, tmp_path: Path) -> None: + """Test topics command when expert has no topics.""" + # Create expert without topics + experts_dir = tmp_path / ".deepwork" / "experts" / "empty_expert" + experts_dir.mkdir(parents=True) + (experts_dir / "expert.yml").write_text( + "discovery_description: Empty expert\nfull_expertise: Nothing here." + ) + + result = runner.invoke( + topics, ["--expert", "empty-expert", "--path", str(tmp_path)] + ) + + assert result.exit_code == 0 + assert "No topics yet" in result.output + + +class TestLearningsCommand: + """Tests for the learnings command.""" + + def test_learnings_command_help(self, runner: CliRunner) -> None: + """Test learnings command shows help.""" + result = runner.invoke(learnings, ["--help"]) + + assert result.exit_code == 0 + assert "List learnings for an expert" in result.output + assert "--expert" in result.output + + def test_learnings_command_requires_expert(self, runner: CliRunner) -> None: + """Test learnings command requires --expert option.""" + result = runner.invoke(learnings, []) + + assert result.exit_code != 0 + + def test_learnings_command_lists_learnings( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test learnings command lists learnings for an expert.""" + result = runner.invoke( + learnings, ["--expert", "test-expert", "--path", str(project_with_expert)] + ) + + assert result.exit_code == 0 + assert "Important Discovery" in result.output + assert "X causes Y" in result.output + + def test_learnings_command_markdown_format( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test learnings command outputs markdown format.""" + result = runner.invoke( + learnings, ["--expert", "test-expert", "--path", str(project_with_expert)] + ) + + assert result.exit_code == 0 + # Should contain markdown links + assert "[Important Discovery]" in result.output + assert "(learnings/" in result.output + + def test_learnings_command_expert_not_found( + self, runner: CliRunner, project_with_expert: Path + ) -> None: + """Test learnings command with nonexistent expert.""" + result = runner.invoke( + learnings, ["--expert", "nonexistent", "--path", str(project_with_expert)] + ) + + assert result.exit_code != 0 + assert "not found" in result.output.lower() + + def test_learnings_command_no_learnings(self, runner: CliRunner, tmp_path: Path) -> None: + """Test learnings command when expert has no learnings.""" + # Create expert without learnings + experts_dir = tmp_path / ".deepwork" / "experts" / "empty_expert" + experts_dir.mkdir(parents=True) + (experts_dir / "expert.yml").write_text( + "discovery_description: Empty expert\nfull_expertise: Nothing here." + ) + + result = runner.invoke( + learnings, ["--expert", "empty-expert", "--path", str(tmp_path)] + ) + + assert result.exit_code == 0 + assert "No learnings yet" in result.output + + +class TestExpertNameResolution: + """Tests for expert name resolution (dashes vs underscores).""" + + def test_expert_with_underscores_resolved( + self, runner: CliRunner, tmp_path: Path + ) -> None: + """Test that expert-name resolves to expert_name folder.""" + # Create expert with underscore folder name + experts_dir = tmp_path / ".deepwork" / "experts" / "rails_activejob" + experts_dir.mkdir(parents=True) + (experts_dir / "expert.yml").write_text( + "discovery_description: Rails ActiveJob\nfull_expertise: Content." + ) + + # Topics directory + topics_dir = experts_dir / "topics" + topics_dir.mkdir() + (topics_dir / "test.md").write_text("---\nname: Test\n---\nContent") + + # Query with dashes + result = runner.invoke( + topics, ["--expert", "rails-activejob", "--path", str(tmp_path)] + ) + + assert result.exit_code == 0 + assert "Test" in result.output + + def test_available_experts_shown_on_error( + self, runner: CliRunner, tmp_path: Path + ) -> None: + """Test that available experts are listed when expert not found.""" + # Create some experts + experts_dir = tmp_path / ".deepwork" / "experts" + experts_dir.mkdir(parents=True) + + for name in ["expert_a", "expert_b"]: + ed = experts_dir / name + ed.mkdir() + (ed / "expert.yml").write_text( + f"discovery_description: {name}\nfull_expertise: Content." + ) + + # Query nonexistent expert + result = runner.invoke( + topics, ["--expert", "nonexistent", "--path", str(tmp_path)] + ) + + assert result.exit_code != 0 + assert "expert-a" in result.output.lower() or "expert_a" in result.output.lower() + assert "expert-b" in result.output.lower() or "expert_b" in result.output.lower() diff --git a/tests/unit/test_experts_generator.py b/tests/unit/test_experts_generator.py new file mode 100644 index 00000000..d5bdd93d --- /dev/null +++ b/tests/unit/test_experts_generator.py @@ -0,0 +1,256 @@ +"""Tests for expert agent generator.""" + +from pathlib import Path + +import pytest + +from deepwork.core.adapters import ClaudeAdapter +from deepwork.core.experts_generator import ExpertGenerator, ExpertGeneratorError +from deepwork.core.experts_parser import ExpertDefinition, Learning, Topic + + +class TestExpertGenerator: + """Tests for ExpertGenerator class.""" + + def test_init_default_templates(self) -> None: + """Test initialization with default templates directory.""" + generator = ExpertGenerator() + + assert generator.templates_dir.exists() + assert (generator.templates_dir / "claude").exists() + + def test_init_custom_templates(self, tmp_path: Path) -> None: + """Test initialization with custom templates directory.""" + templates_dir = tmp_path / "templates" + templates_dir.mkdir() + + generator = ExpertGenerator(templates_dir) + + assert generator.templates_dir == templates_dir + + def test_init_nonexistent_templates(self, tmp_path: Path) -> None: + """Test initialization with nonexistent templates fails.""" + with pytest.raises(ExpertGeneratorError, match="not found"): + ExpertGenerator(tmp_path / "nonexistent") + + def test_get_agent_filename(self) -> None: + """Test agent filename generation.""" + generator = ExpertGenerator() + + assert generator.get_agent_filename("rails-activejob") == "dwe_rails-activejob.md" + assert generator.get_agent_filename("experts") == "dwe_experts.md" + + def test_get_agent_name(self) -> None: + """Test agent name generation.""" + generator = ExpertGenerator() + + assert generator.get_agent_name("rails-activejob") == "rails-activejob-expert" + assert generator.get_agent_name("experts") == "experts-expert" + + +class TestGenerateExpertAgent: + """Tests for generating expert agent files.""" + + @pytest.fixture + def generator(self) -> ExpertGenerator: + """Create a generator instance.""" + return ExpertGenerator() + + @pytest.fixture + def claude_adapter(self, tmp_path: Path) -> ClaudeAdapter: + """Create a Claude adapter.""" + return ClaudeAdapter(project_root=tmp_path) + + @pytest.fixture + def sample_expert(self, tmp_path: Path) -> ExpertDefinition: + """Create a sample expert definition.""" + expert_dir = tmp_path / "rails_activejob" + expert_dir.mkdir(parents=True) + + return ExpertDefinition( + name="rails-activejob", + discovery_description="Rails ActiveJob background processing", + full_expertise="You are an expert on Rails ActiveJob.\n\n## Key Concepts\n\n- Queues\n- Retries", + expert_dir=expert_dir, + topics=[ + Topic(name="Retry Handling", keywords=["retry"], source_file=expert_dir / "topics/retry.md"), + ], + learnings=[ + Learning(name="Sentry Issue", summarized_result="Fixed it", source_file=expert_dir / "learnings/sentry.md"), + ], + ) + + def test_generate_expert_agent_creates_file( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, sample_expert: ExpertDefinition, tmp_path: Path + ) -> None: + """Test that generating an expert agent creates the file.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + agent_path = generator.generate_expert_agent(sample_expert, claude_adapter, output_dir) + + assert agent_path.exists() + assert agent_path.name == "dwe_rails-activejob.md" + assert agent_path.parent.name == "agents" + + def test_generate_expert_agent_content( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, sample_expert: ExpertDefinition, tmp_path: Path + ) -> None: + """Test the content of generated expert agent file.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + agent_path = generator.generate_expert_agent(sample_expert, claude_adapter, output_dir) + content = agent_path.read_text() + + # Check frontmatter + assert "name: rails-activejob-expert" in content + assert "Rails ActiveJob" in content + + # Check full_expertise is included + assert "expert on Rails ActiveJob" in content + assert "Key Concepts" in content + + # Check dynamic command embedding + assert '$(deepwork topics --expert "rails-activejob")' in content + assert '$(deepwork learnings --expert "rails-activejob")' in content + + def test_generate_expert_agent_creates_agents_dir( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, sample_expert: ExpertDefinition, tmp_path: Path + ) -> None: + """Test that generating creates the agents directory if needed.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + assert not (output_dir / "agents").exists() + + generator.generate_expert_agent(sample_expert, claude_adapter, output_dir) + + assert (output_dir / "agents").exists() + + def test_generate_all_expert_agents( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, tmp_path: Path + ) -> None: + """Test generating agents for multiple experts.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + expert1 = ExpertDefinition( + name="expert-one", + discovery_description="First expert", + full_expertise="Expert one content", + expert_dir=tmp_path / "expert_one", + ) + expert2 = ExpertDefinition( + name="expert-two", + discovery_description="Second expert", + full_expertise="Expert two content", + expert_dir=tmp_path / "expert_two", + ) + + agent_paths = generator.generate_all_expert_agents([expert1, expert2], claude_adapter, output_dir) + + assert len(agent_paths) == 2 + assert all(p.exists() for p in agent_paths) + assert {p.name for p in agent_paths} == {"dwe_expert-one.md", "dwe_expert-two.md"} + + def test_generate_empty_experts_list( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, tmp_path: Path + ) -> None: + """Test generating with empty experts list.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + agent_paths = generator.generate_all_expert_agents([], claude_adapter, output_dir) + + assert agent_paths == [] + + +class TestExpertAgentTemplate: + """Tests for the expert agent template structure.""" + + @pytest.fixture + def generator(self) -> ExpertGenerator: + """Create a generator instance.""" + return ExpertGenerator() + + @pytest.fixture + def claude_adapter(self, tmp_path: Path) -> ClaudeAdapter: + """Create a Claude adapter.""" + return ClaudeAdapter(project_root=tmp_path) + + def test_template_has_yaml_frontmatter( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, tmp_path: Path + ) -> None: + """Test that generated agent has YAML frontmatter.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + expert = ExpertDefinition( + name="test-expert", + discovery_description="Test description", + full_expertise="Test expertise", + expert_dir=tmp_path / "test_expert", + ) + + agent_path = generator.generate_expert_agent(expert, claude_adapter, output_dir) + content = agent_path.read_text() + + # Check YAML frontmatter markers + assert content.startswith("---\n") + lines = content.split("\n") + # Find second --- + second_marker = None + for i, line in enumerate(lines[1:], 1): + if line == "---": + second_marker = i + break + assert second_marker is not None, "YAML frontmatter not properly closed" + + def test_template_escapes_description( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, tmp_path: Path + ) -> None: + """Test that description with quotes is properly escaped.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + expert = ExpertDefinition( + name="test-expert", + discovery_description='Description with "quotes" inside', + full_expertise="Test expertise", + expert_dir=tmp_path / "test_expert", + ) + + agent_path = generator.generate_expert_agent(expert, claude_adapter, output_dir) + content = agent_path.read_text() + + # Should escape quotes in description + assert r'\"quotes\"' in content or "quotes" in content + + def test_template_truncates_long_description( + self, generator: ExpertGenerator, claude_adapter: ClaudeAdapter, tmp_path: Path + ) -> None: + """Test that long descriptions are truncated.""" + output_dir = tmp_path / ".claude" + output_dir.mkdir() + + # Create a very long description + long_description = "A" * 500 + + expert = ExpertDefinition( + name="test-expert", + discovery_description=long_description, + full_expertise="Test expertise", + expert_dir=tmp_path / "test_expert", + ) + + agent_path = generator.generate_expert_agent(expert, claude_adapter, output_dir) + content = agent_path.read_text() + + # Extract description from frontmatter + lines = content.split("\n") + for line in lines: + if line.startswith("description:"): + # Should be truncated + assert len(line) < 500 + break diff --git a/tests/unit/test_experts_parser.py b/tests/unit/test_experts_parser.py new file mode 100644 index 00000000..a8e89c4b --- /dev/null +++ b/tests/unit/test_experts_parser.py @@ -0,0 +1,563 @@ +"""Tests for expert definition parser.""" + +from datetime import date +from pathlib import Path + +import pytest + +from deepwork.core.experts_parser import ( + ExpertDefinition, + ExpertParseError, + Learning, + Topic, + _folder_name_to_expert_name, + discover_experts, + format_learnings_markdown, + format_topics_markdown, + parse_expert_definition, + parse_learning_file, + parse_topic_file, +) + + +class TestFolderNameConversion: + """Tests for folder name to expert name conversion.""" + + def test_underscores_to_dashes(self) -> None: + """Test that underscores are converted to dashes.""" + assert _folder_name_to_expert_name("rails_activejob") == "rails-activejob" + + def test_spaces_to_dashes(self) -> None: + """Test that spaces are converted to dashes.""" + assert _folder_name_to_expert_name("rails activejob") == "rails-activejob" + + def test_mixed_conversion(self) -> None: + """Test mixed underscores and spaces.""" + assert _folder_name_to_expert_name("rails_active job") == "rails-active-job" + + def test_no_conversion_needed(self) -> None: + """Test name that doesn't need conversion.""" + assert _folder_name_to_expert_name("experts") == "experts" + + def test_already_dashes(self) -> None: + """Test name that already has dashes.""" + assert _folder_name_to_expert_name("rails-activejob") == "rails-activejob" + + +class TestTopic: + """Tests for Topic dataclass.""" + + def test_from_dict_minimal(self) -> None: + """Test creating topic from minimal dict.""" + data = {"name": "Test Topic"} + topic = Topic.from_dict(data) + + assert topic.name == "Test Topic" + assert topic.keywords == [] + assert topic.last_updated is None + assert topic.body == "" + + def test_from_dict_full(self) -> None: + """Test creating topic from full dict.""" + data = { + "name": "Retry Handling", + "keywords": ["retry", "backoff"], + "last_updated": "2025-01-30", + } + topic = Topic.from_dict(data, body="Content here", source_file=Path("topics/retry.md")) + + assert topic.name == "Retry Handling" + assert topic.keywords == ["retry", "backoff"] + assert topic.last_updated == date(2025, 1, 30) + assert topic.body == "Content here" + assert topic.source_file == Path("topics/retry.md") + + def test_relative_path(self) -> None: + """Test relative path generation.""" + topic = Topic(name="Test", source_file=Path("/some/path/topics/test.md")) + assert topic.relative_path == "topics/test.md" + + def test_relative_path_no_source(self) -> None: + """Test relative path when no source file.""" + topic = Topic(name="Test") + assert topic.relative_path is None + + +class TestLearning: + """Tests for Learning dataclass.""" + + def test_from_dict_minimal(self) -> None: + """Test creating learning from minimal dict.""" + data = {"name": "Test Learning"} + learning = Learning.from_dict(data) + + assert learning.name == "Test Learning" + assert learning.last_updated is None + assert learning.summarized_result is None + assert learning.body == "" + + def test_from_dict_full(self) -> None: + """Test creating learning from full dict.""" + data = { + "name": "Job errors not going to Sentry", + "last_updated": "2025-01-20", + "summarized_result": "Sentry changed their gem.", + } + learning = Learning.from_dict( + data, body="Full content", source_file=Path("learnings/sentry.md") + ) + + assert learning.name == "Job errors not going to Sentry" + assert learning.last_updated == date(2025, 1, 20) + assert learning.summarized_result == "Sentry changed their gem." + assert learning.body == "Full content" + assert learning.source_file == Path("learnings/sentry.md") + + def test_relative_path(self) -> None: + """Test relative path generation.""" + learning = Learning(name="Test", source_file=Path("/some/path/learnings/test.md")) + assert learning.relative_path == "learnings/test.md" + + +class TestExpertDefinition: + """Tests for ExpertDefinition dataclass.""" + + def test_from_dict(self) -> None: + """Test creating expert definition from dict.""" + data = { + "discovery_description": "Test expert", + "full_expertise": "You are an expert.", + } + expert = ExpertDefinition.from_dict(data, Path("/path/to/rails_activejob")) + + assert expert.name == "rails-activejob" + assert expert.discovery_description == "Test expert" + assert expert.full_expertise == "You are an expert." + assert expert.expert_dir == Path("/path/to/rails_activejob") + assert expert.topics == [] + assert expert.learnings == [] + + def test_from_dict_with_topics_and_learnings(self) -> None: + """Test creating expert with topics and learnings.""" + data = { + "discovery_description": "Test expert", + "full_expertise": "You are an expert.", + } + topics = [Topic(name="Topic 1"), Topic(name="Topic 2")] + learnings = [Learning(name="Learning 1")] + + expert = ExpertDefinition.from_dict( + data, Path("/path/to/test_expert"), topics=topics, learnings=learnings + ) + + assert len(expert.topics) == 2 + assert len(expert.learnings) == 1 + + def test_get_topics_sorted(self) -> None: + """Test topics are sorted by most recently updated.""" + topics = [ + Topic(name="Old", last_updated=date(2025, 1, 1)), + Topic(name="New", last_updated=date(2025, 1, 30)), + Topic(name="No Date"), + ] + expert = ExpertDefinition( + name="test", + discovery_description="Test", + full_expertise="Test", + expert_dir=Path("/test"), + topics=topics, + ) + + sorted_topics = expert.get_topics_sorted() + assert sorted_topics[0].name == "New" + assert sorted_topics[1].name == "Old" + assert sorted_topics[2].name == "No Date" + + def test_get_learnings_sorted(self) -> None: + """Test learnings are sorted by most recently updated.""" + learnings = [ + Learning(name="Old", last_updated=date(2025, 1, 1)), + Learning(name="New", last_updated=date(2025, 1, 30)), + Learning(name="No Date"), + ] + expert = ExpertDefinition( + name="test", + discovery_description="Test", + full_expertise="Test", + expert_dir=Path("/test"), + learnings=learnings, + ) + + sorted_learnings = expert.get_learnings_sorted() + assert sorted_learnings[0].name == "New" + assert sorted_learnings[1].name == "Old" + assert sorted_learnings[2].name == "No Date" + + +class TestParseTopicFile: + """Tests for parsing topic files.""" + + def test_parse_valid_topic(self, tmp_path: Path) -> None: + """Test parsing a valid topic file.""" + topic_file = tmp_path / "test_topic.md" + topic_file.write_text( + """--- +name: Test Topic +keywords: + - testing + - unit test +last_updated: 2025-01-30 +--- + +This is the topic content. +""" + ) + + topic = parse_topic_file(topic_file) + + assert topic.name == "Test Topic" + assert topic.keywords == ["testing", "unit test"] + assert topic.last_updated == date(2025, 1, 30) + assert "topic content" in topic.body + assert topic.source_file == topic_file + + def test_parse_minimal_topic(self, tmp_path: Path) -> None: + """Test parsing a minimal topic file.""" + topic_file = tmp_path / "minimal.md" + topic_file.write_text( + """--- +name: Minimal Topic +--- + +Content here. +""" + ) + + topic = parse_topic_file(topic_file) + + assert topic.name == "Minimal Topic" + assert topic.keywords == [] + assert topic.last_updated is None + + def test_parse_topic_missing_frontmatter(self, tmp_path: Path) -> None: + """Test parsing topic without frontmatter fails.""" + topic_file = tmp_path / "no_frontmatter.md" + topic_file.write_text("Just content without frontmatter") + + with pytest.raises(ExpertParseError, match="frontmatter"): + parse_topic_file(topic_file) + + def test_parse_topic_missing_name(self, tmp_path: Path) -> None: + """Test parsing topic without name fails.""" + topic_file = tmp_path / "no_name.md" + topic_file.write_text( + """--- +keywords: + - test +--- + +Content +""" + ) + + with pytest.raises(ExpertParseError, match="name"): + parse_topic_file(topic_file) + + def test_parse_topic_nonexistent(self, tmp_path: Path) -> None: + """Test parsing nonexistent topic file fails.""" + with pytest.raises(ExpertParseError, match="does not exist"): + parse_topic_file(tmp_path / "nonexistent.md") + + +class TestParseLearningFile: + """Tests for parsing learning files.""" + + def test_parse_valid_learning(self, tmp_path: Path) -> None: + """Test parsing a valid learning file.""" + learning_file = tmp_path / "test_learning.md" + learning_file.write_text( + """--- +name: Test Learning +last_updated: 2025-01-30 +summarized_result: | + Discovered that X causes Y. +--- + +## Context +Full learning content here. +""" + ) + + learning = parse_learning_file(learning_file) + + assert learning.name == "Test Learning" + assert learning.last_updated == date(2025, 1, 30) + assert "Discovered that X causes Y" in learning.summarized_result + assert "Full learning content" in learning.body + + def test_parse_minimal_learning(self, tmp_path: Path) -> None: + """Test parsing a minimal learning file.""" + learning_file = tmp_path / "minimal.md" + learning_file.write_text( + """--- +name: Minimal Learning +--- + +Content here. +""" + ) + + learning = parse_learning_file(learning_file) + + assert learning.name == "Minimal Learning" + assert learning.last_updated is None + assert learning.summarized_result is None + + def test_parse_learning_missing_frontmatter(self, tmp_path: Path) -> None: + """Test parsing learning without frontmatter fails.""" + learning_file = tmp_path / "no_frontmatter.md" + learning_file.write_text("Just content") + + with pytest.raises(ExpertParseError, match="frontmatter"): + parse_learning_file(learning_file) + + +class TestParseExpertDefinition: + """Tests for parsing expert definitions.""" + + def test_parse_valid_expert(self, tmp_path: Path) -> None: + """Test parsing a valid expert definition.""" + expert_dir = tmp_path / "test_expert" + expert_dir.mkdir() + + # Create expert.yml + (expert_dir / "expert.yml").write_text( + """discovery_description: | + Test expert for unit testing + +full_expertise: | + You are an expert on testing. +""" + ) + + # Create topics directory with a topic + topics_dir = expert_dir / "topics" + topics_dir.mkdir() + (topics_dir / "basics.md").write_text( + """--- +name: Testing Basics +keywords: + - basics +last_updated: 2025-01-30 +--- + +Content +""" + ) + + # Create learnings directory with a learning + learnings_dir = expert_dir / "learnings" + learnings_dir.mkdir() + (learnings_dir / "discovery.md").write_text( + """--- +name: Important Discovery +last_updated: 2025-01-20 +summarized_result: Found something important. +--- + +Details +""" + ) + + expert = parse_expert_definition(expert_dir) + + assert expert.name == "test-expert" + assert "unit testing" in expert.discovery_description + assert "expert on testing" in expert.full_expertise + assert len(expert.topics) == 1 + assert expert.topics[0].name == "Testing Basics" + assert len(expert.learnings) == 1 + assert expert.learnings[0].name == "Important Discovery" + + def test_parse_expert_no_topics_or_learnings(self, tmp_path: Path) -> None: + """Test parsing expert without topics or learnings directories.""" + expert_dir = tmp_path / "minimal_expert" + expert_dir.mkdir() + + (expert_dir / "expert.yml").write_text( + """discovery_description: Minimal expert +full_expertise: Minimal expertise. +""" + ) + + expert = parse_expert_definition(expert_dir) + + assert expert.name == "minimal-expert" + assert expert.topics == [] + assert expert.learnings == [] + + def test_parse_expert_missing_expert_yml(self, tmp_path: Path) -> None: + """Test parsing expert without expert.yml fails.""" + expert_dir = tmp_path / "no_yml" + expert_dir.mkdir() + + with pytest.raises(ExpertParseError, match="expert.yml not found"): + parse_expert_definition(expert_dir) + + def test_parse_expert_nonexistent_dir(self, tmp_path: Path) -> None: + """Test parsing nonexistent directory fails.""" + with pytest.raises(ExpertParseError, match="does not exist"): + parse_expert_definition(tmp_path / "nonexistent") + + def test_parse_expert_invalid_yml(self, tmp_path: Path) -> None: + """Test parsing expert with invalid YAML fails.""" + expert_dir = tmp_path / "invalid" + expert_dir.mkdir() + (expert_dir / "expert.yml").write_text("discovery_description: only one field") + + with pytest.raises(ExpertParseError, match="full_expertise"): + parse_expert_definition(expert_dir) + + +class TestDiscoverExperts: + """Tests for discovering expert directories.""" + + def test_discover_experts_multiple(self, tmp_path: Path) -> None: + """Test discovering multiple experts.""" + experts_dir = tmp_path / "experts" + experts_dir.mkdir() + + # Create two expert directories + for name in ["expert_a", "expert_b"]: + expert_dir = experts_dir / name + expert_dir.mkdir() + (expert_dir / "expert.yml").write_text( + f"discovery_description: {name}\nfull_expertise: Content" + ) + + expert_dirs = discover_experts(experts_dir) + + assert len(expert_dirs) == 2 + names = {d.name for d in expert_dirs} + assert names == {"expert_a", "expert_b"} + + def test_discover_experts_empty(self, tmp_path: Path) -> None: + """Test discovering experts in empty directory.""" + experts_dir = tmp_path / "experts" + experts_dir.mkdir() + + expert_dirs = discover_experts(experts_dir) + + assert expert_dirs == [] + + def test_discover_experts_nonexistent(self, tmp_path: Path) -> None: + """Test discovering experts in nonexistent directory.""" + expert_dirs = discover_experts(tmp_path / "nonexistent") + + assert expert_dirs == [] + + def test_discover_experts_ignores_non_expert_dirs(self, tmp_path: Path) -> None: + """Test that directories without expert.yml are ignored.""" + experts_dir = tmp_path / "experts" + experts_dir.mkdir() + + # Valid expert + valid_dir = experts_dir / "valid_expert" + valid_dir.mkdir() + (valid_dir / "expert.yml").write_text( + "discovery_description: Valid\nfull_expertise: Content" + ) + + # Invalid - no expert.yml + invalid_dir = experts_dir / "not_an_expert" + invalid_dir.mkdir() + (invalid_dir / "readme.md").write_text("Not an expert") + + expert_dirs = discover_experts(experts_dir) + + assert len(expert_dirs) == 1 + assert expert_dirs[0].name == "valid_expert" + + +class TestFormatTopicsMarkdown: + """Tests for formatting topics as markdown.""" + + def test_format_topics_empty(self) -> None: + """Test formatting empty topics list.""" + expert = ExpertDefinition( + name="test", + discovery_description="Test", + full_expertise="Test", + expert_dir=Path("/test"), + topics=[], + ) + + result = format_topics_markdown(expert) + + assert result == "_No topics yet._" + + def test_format_topics_with_content(self) -> None: + """Test formatting topics with content.""" + topics = [ + Topic( + name="First Topic", + keywords=["key1", "key2"], + source_file=Path("/test/topics/first.md"), + ), + Topic(name="Second Topic", source_file=Path("/test/topics/second.md")), + ] + expert = ExpertDefinition( + name="test", + discovery_description="Test", + full_expertise="Test", + expert_dir=Path("/test"), + topics=topics, + ) + + result = format_topics_markdown(expert) + + assert "[First Topic](topics/first.md)" in result + assert "[Second Topic](topics/second.md)" in result + assert "Keywords: key1, key2" in result + + +class TestFormatLearningsMarkdown: + """Tests for formatting learnings as markdown.""" + + def test_format_learnings_empty(self) -> None: + """Test formatting empty learnings list.""" + expert = ExpertDefinition( + name="test", + discovery_description="Test", + full_expertise="Test", + expert_dir=Path("/test"), + learnings=[], + ) + + result = format_learnings_markdown(expert) + + assert result == "_No learnings yet._" + + def test_format_learnings_with_content(self) -> None: + """Test formatting learnings with content.""" + learnings = [ + Learning( + name="First Learning", + summarized_result="Found something important.", + source_file=Path("/test/learnings/first.md"), + ), + Learning(name="Second Learning", source_file=Path("/test/learnings/second.md")), + ] + expert = ExpertDefinition( + name="test", + discovery_description="Test", + full_expertise="Test", + expert_dir=Path("/test"), + learnings=learnings, + ) + + result = format_learnings_markdown(expert) + + assert "[First Learning](learnings/first.md)" in result + assert "[Second Learning](learnings/second.md)" in result + assert "Found something important" in result diff --git a/uv.lock b/uv.lock index 5c61745e..cecf3f82 100644 --- a/uv.lock +++ b/uv.lock @@ -126,7 +126,7 @@ toml = [ [[package]] name = "deepwork" -version = "0.5.1" +version = "0.6.0" source = { editable = "." } dependencies = [ { name = "click" }, From cd3856c1242957e1ee707afc6843a13fa886ee6e Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Fri, 30 Jan 2026 15:56:44 -0700 Subject: [PATCH 3/9] docs: Update experts system status to implemented Remove "(Planned)" from section heading and update status to reflect that the experts system implementation is now complete. Co-Authored-By: Claude Opus 4.5 --- doc/architecture.md | 4 +--- doc/experts_requirements.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/architecture.md b/doc/architecture.md index 795f51f7..fbbcaaad 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -1351,12 +1351,10 @@ Claude: Created rule "API documentation update" in .deepwork/rules/api-documenta --- -## Experts (Planned) +## Experts Experts are auto-improving collections of domain knowledge. They provide a structured mechanism for accumulating expertise and exposing it through Claude agents. -**Status**: Specification complete, implementation pending. - See `doc/experts_requirements.md` for the full specification. **Key Concepts**: diff --git a/doc/experts_requirements.md b/doc/experts_requirements.md index 7906b8f2..055f7229 100644 --- a/doc/experts_requirements.md +++ b/doc/experts_requirements.md @@ -1,6 +1,6 @@ # Experts System -> **Status**: Specification complete, implementation pending. This document describes planned functionality. +> **Status**: Implemented. See `doc/architecture.md` for integration details. Experts are auto-improving collections of domain knowledge. They provide a structured mechanism for accumulating expertise and exposing it throughout the system. From 13edb5bc9f589127a7c649096ef59fda1bdb9a6e Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Fri, 30 Jan 2026 16:12:31 -0700 Subject: [PATCH 4/9] fix naming --- .claude/agents/dwe_experts.md | 4 ++-- .claude/settings.json | 3 +++ .deepwork/experts/experts/expert.yml | 2 +- CHANGELOG.md | 2 +- doc/experts_requirements.md | 2 +- flake.nix | 4 ++-- pyproject.toml | 10 ++++++++++ src/deepwork/core/experts_generator.py | 4 ++-- .../standard/experts/experts/expert.yml | 2 +- .../templates/claude/agent-expert.md.jinja | 2 +- tests/integration/test_experts_sync.py | 2 +- tests/unit/test_experts_generator.py | 6 +++--- uv.lock | 20 +++++++++++++++++++ 13 files changed, 48 insertions(+), 15 deletions(-) diff --git a/.claude/agents/dwe_experts.md b/.claude/agents/dwe_experts.md index 1a892b03..a86d360e 100644 --- a/.claude/agents/dwe_experts.md +++ b/.claude/agents/dwe_experts.md @@ -1,5 +1,5 @@ --- -name: experts-expert +name: experts description: "DeepWork experts system - creating, organizing, and evolving domain knowledge collections that auto-improve through topics and learnings." --- @@ -158,7 +158,7 @@ Returns markdown list with links, summaries, sorted by last_updated. Running `deepwork sync` generates Claude agents in `.claude/agents/`: - Filename: `dwe_[expert-name].md` -- Agent name: `[expert-name]-expert` +- Agent name: `[expert-name]` - Body: full_expertise + dynamic topic/learning lists The dynamic embedding ensures agents always access current topics and learnings: diff --git a/.claude/settings.json b/.claude/settings.json index cf4e3c4c..cc18d55b 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,8 @@ { "permissions": { + "deny": [ + "Bash(gh pr merge:*)" + ], "allow": [ "WebFetch(domain:code.claude.com)", "WebFetch(domain:www.anthropic.com)", diff --git a/.deepwork/experts/experts/expert.yml b/.deepwork/experts/experts/expert.yml index 94cced9c..d3e9c385 100644 --- a/.deepwork/experts/experts/expert.yml +++ b/.deepwork/experts/experts/expert.yml @@ -158,7 +158,7 @@ full_expertise: | Running `deepwork sync` generates Claude agents in `.claude/agents/`: - Filename: `dwe_[expert-name].md` - - Agent name: `[expert-name]-expert` + - Agent name: `[expert-name]` - Body: full_expertise + dynamic topic/learning lists The dynamic embedding ensures agents always access current topics and learnings: diff --git a/CHANGELOG.md b/CHANGELOG.md index 4277c9dc..47097cd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,7 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `deepwork learnings --expert "name"` - Lists learnings as markdown with summarized results - Expert agent generation during `deepwork sync`: - Generates Claude agents in `.claude/agents/dwe_[expert-name].md` - - Agent name format: `[expert-name]-expert` + - Agent name format: `[expert-name]` - Uses dynamic command embedding (`$(deepwork topics ...)`) for always-current content - Standard "experts" expert shipped with DeepWork documenting the experts system itself - Includes topics on design patterns and discovery descriptions diff --git a/doc/experts_requirements.md b/doc/experts_requirements.md index 055f7229..c6037590 100644 --- a/doc/experts_requirements.md +++ b/doc/experts_requirements.md @@ -135,7 +135,7 @@ Returns a Markdown list of learnings: Agents are created in `.claude/agents/` with: - **Filename**: `dwe_[expert-name].md` (e.g., `dwe_rails-activejob.md`) -- **name field**: `[expert-name]-expert` (e.g., `rails-activejob-expert`) +- **name field**: `[expert-name]` (e.g., `rails-activejob`) - **description**: The `discovery_description` from expert.yml ### Agent Body Content diff --git a/flake.nix b/flake.nix index d2218afb..b39b2ed3 100644 --- a/flake.nix +++ b/flake.nix @@ -68,9 +68,9 @@ uv venv .venv --quiet fi - # Sync dependencies (including dev extras like pytest, ruff, mypy) + # Sync dependencies (including dev group: pytest, ruff, mypy) # Run quietly - uv only outputs when changes are needed - uv sync --all-extras --quiet 2>/dev/null || uv sync --all-extras + uv sync --group dev --quiet 2>/dev/null || uv sync --group dev # Activate venv by setting environment variables directly # This works reliably for both interactive shells and `nix develop --command` diff --git a/pyproject.toml b/pyproject.toml index 57d7de93..d62ee237 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,16 @@ dev = [ "types-PyYAML", ] +[dependency-groups] +dev = [ + "pytest>=7.0", + "pytest-mock>=3.10", + "pytest-cov>=4.0", + "ruff>=0.1.0", + "mypy>=1.0", + "types-PyYAML", +] + [project.scripts] deepwork = "deepwork.cli.main:cli" diff --git a/src/deepwork/core/experts_generator.py b/src/deepwork/core/experts_generator.py index 023e57c1..d69fac56 100644 --- a/src/deepwork/core/experts_generator.py +++ b/src/deepwork/core/experts_generator.py @@ -97,9 +97,9 @@ def get_agent_name(self, expert_name: str) -> str: expert_name: Name of the expert (e.g., "rails-activejob") Returns: - Agent name (e.g., "rails-activejob-expert") + Agent name (e.g., "rails-activejob") """ - return f"{expert_name}-expert" + return expert_name def generate_expert_agent( self, diff --git a/src/deepwork/standard/experts/experts/expert.yml b/src/deepwork/standard/experts/experts/expert.yml index 94cced9c..d3e9c385 100644 --- a/src/deepwork/standard/experts/experts/expert.yml +++ b/src/deepwork/standard/experts/experts/expert.yml @@ -158,7 +158,7 @@ full_expertise: | Running `deepwork sync` generates Claude agents in `.claude/agents/`: - Filename: `dwe_[expert-name].md` - - Agent name: `[expert-name]-expert` + - Agent name: `[expert-name]` - Body: full_expertise + dynamic topic/learning lists The dynamic embedding ensures agents always access current topics and learnings: diff --git a/src/deepwork/templates/claude/agent-expert.md.jinja b/src/deepwork/templates/claude/agent-expert.md.jinja index b7e0599d..bfb02c14 100644 --- a/src/deepwork/templates/claude/agent-expert.md.jinja +++ b/src/deepwork/templates/claude/agent-expert.md.jinja @@ -10,7 +10,7 @@ Template Variables: - learnings_count: int - Number of learnings in this expert #} --- -name: {{ expert_name }}-expert +name: {{ expert_name }} description: "{{ discovery_description | replace('"', '\\"') | replace('\n', ' ') | truncate(200) }}" --- diff --git a/tests/integration/test_experts_sync.py b/tests/integration/test_experts_sync.py index c829d4c4..bf0cb147 100644 --- a/tests/integration/test_experts_sync.py +++ b/tests/integration/test_experts_sync.py @@ -104,7 +104,7 @@ def test_sync_agent_has_correct_name(self, project_with_experts: Path) -> None: agent_file = project_with_experts / ".claude" / "agents" / "dwe_test-expert.md" content = agent_file.read_text() - assert "name: test-expert-expert" in content + assert "name: test-expert" in content def test_sync_agent_has_description(self, project_with_experts: Path) -> None: """Test that generated agent has description from discovery_description.""" diff --git a/tests/unit/test_experts_generator.py b/tests/unit/test_experts_generator.py index d5bdd93d..7ca76065 100644 --- a/tests/unit/test_experts_generator.py +++ b/tests/unit/test_experts_generator.py @@ -44,8 +44,8 @@ def test_get_agent_name(self) -> None: """Test agent name generation.""" generator = ExpertGenerator() - assert generator.get_agent_name("rails-activejob") == "rails-activejob-expert" - assert generator.get_agent_name("experts") == "experts-expert" + assert generator.get_agent_name("rails-activejob") == "rails-activejob" + assert generator.get_agent_name("experts") == "experts" class TestGenerateExpertAgent: @@ -104,7 +104,7 @@ def test_generate_expert_agent_content( content = agent_path.read_text() # Check frontmatter - assert "name: rails-activejob-expert" in content + assert "name: rails-activejob" in content assert "Rails ActiveJob" in content # Check full_expertise is included diff --git a/uv.lock b/uv.lock index cecf3f82..433ce43a 100644 --- a/uv.lock +++ b/uv.lock @@ -147,6 +147,16 @@ dev = [ { name = "types-pyyaml" }, ] +[package.dev-dependencies] +dev = [ + { name = "mypy" }, + { name = "pytest" }, + { name = "pytest-cov" }, + { name = "pytest-mock" }, + { name = "ruff" }, + { name = "types-pyyaml" }, +] + [package.metadata] requires-dist = [ { name = "click", specifier = ">=8.1.0" }, @@ -164,6 +174,16 @@ requires-dist = [ ] provides-extras = ["dev"] +[package.metadata.requires-dev] +dev = [ + { name = "mypy", specifier = ">=1.0" }, + { name = "pytest", specifier = ">=7.0" }, + { name = "pytest-cov", specifier = ">=4.0" }, + { name = "pytest-mock", specifier = ">=3.10" }, + { name = "ruff", specifier = ">=0.1.0" }, + { name = "types-pyyaml" }, +] + [[package]] name = "gitdb" version = "4.0.12" From 2c75884e45c46e69a96ed44e59a76b9f4bc13864 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Fri, 30 Jan 2026 16:24:04 -0700 Subject: [PATCH 5/9] Jobs expert --- .claude/agents/dwe_deepwork-jobs.md | 301 ++++++++++++++++++ .deepwork/experts/deepwork_jobs/expert.yml | 285 +++++++++++++++++ .../experts/deepwork_jobs/learnings/.gitkeep | 1 + .../learnings/prompt_hooks_not_executed.md | 50 +++ .../topics/hooks_and_validation.md | 197 ++++++++++++ .../deepwork_jobs/topics/job_yml_schema.md | 153 +++++++++ .../deepwork_jobs/topics/skill_generation.md | 155 +++++++++ .../deepwork_jobs/topics/step_instructions.md | 187 +++++++++++ .../standard/experts/deepwork_jobs/expert.yml | 285 +++++++++++++++++ .../experts/deepwork_jobs/learnings/.gitkeep | 1 + .../learnings/prompt_hooks_not_executed.md | 50 +++ .../topics/hooks_and_validation.md | 197 ++++++++++++ .../deepwork_jobs/topics/job_yml_schema.md | 153 +++++++++ .../deepwork_jobs/topics/skill_generation.md | 155 +++++++++ .../deepwork_jobs/topics/step_instructions.md | 187 +++++++++++ 15 files changed, 2357 insertions(+) create mode 100644 .claude/agents/dwe_deepwork-jobs.md create mode 100644 .deepwork/experts/deepwork_jobs/expert.yml create mode 100644 .deepwork/experts/deepwork_jobs/learnings/.gitkeep create mode 100644 .deepwork/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md create mode 100644 .deepwork/experts/deepwork_jobs/topics/hooks_and_validation.md create mode 100644 .deepwork/experts/deepwork_jobs/topics/job_yml_schema.md create mode 100644 .deepwork/experts/deepwork_jobs/topics/skill_generation.md create mode 100644 .deepwork/experts/deepwork_jobs/topics/step_instructions.md create mode 100644 src/deepwork/standard/experts/deepwork_jobs/expert.yml create mode 100644 src/deepwork/standard/experts/deepwork_jobs/learnings/.gitkeep create mode 100644 src/deepwork/standard/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md create mode 100644 src/deepwork/standard/experts/deepwork_jobs/topics/hooks_and_validation.md create mode 100644 src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md create mode 100644 src/deepwork/standard/experts/deepwork_jobs/topics/skill_generation.md create mode 100644 src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md diff --git a/.claude/agents/dwe_deepwork-jobs.md b/.claude/agents/dwe_deepwork-jobs.md new file mode 100644 index 00000000..3725cecc --- /dev/null +++ b/.claude/agents/dwe_deepwork-jobs.md @@ -0,0 +1,301 @@ +--- +name: deepwork-jobs +description: "DeepWork Jobs system - defining, implementing, and syncing multi-step AI workflows. Covers job.yml schema, step instructions, skill generation, hooks, and CLI commands." +--- + +# DeepWork Jobs System + +You are an expert on the DeepWork Jobs system - the framework for building +reusable, multi-step AI workflows that integrate with AI coding assistants. + +## Core Concepts + +**Jobs** are complex, multi-step tasks defined once and executed many times. +Each job consists of: + +- **job.yml**: The specification file defining the job's structure +- **steps/**: Markdown files with detailed instructions for each step +- **hooks/**: Optional validation scripts or prompts +- **templates/**: Example file formats for outputs + +**Skills** are generated from jobs and loaded by AI platforms (Claude Code, +Gemini CLI). Each step becomes a slash command the user can invoke. + +## Job Definition Structure + +Jobs live in `.deepwork/jobs/[job_name]/`: + +``` +.deepwork/jobs/ +└── competitive_research/ + ├── job.yml + ├── steps/ + │ ├── identify_competitors.md + │ └── research_competitors.md + ├── hooks/ + │ └── validate_research.sh + └── templates/ + └── competitor_profile.md +``` + +## The job.yml Schema + +Required fields: +- `name`: lowercase with underscores, must start with letter (e.g., `competitive_research`) +- `version`: semantic versioning X.Y.Z (e.g., `1.0.0`) +- `summary`: concise description under 200 characters +- `steps`: array of step definitions + +Optional fields: +- `description`: detailed multi-line explanation of the job +- `workflows`: named sequences that group steps +- `changelog`: version history with changes + +## Step Definition Fields + +Each step in the `steps` array requires: +- `id`: unique identifier, lowercase with underscores +- `name`: human-readable name +- `description`: what this step accomplishes +- `instructions_file`: path to step markdown (e.g., `steps/identify.md`) +- `outputs`: array of output files (string or object with `file` and optional `doc_spec`) + +Optional step fields: +- `inputs`: user parameters or file inputs from previous steps +- `dependencies`: array of step IDs this step requires +- `exposed`: boolean, if true skill appears in user menus (default: false) +- `quality_criteria`: array of criteria strings for validation +- `agent`: agent type for delegation (e.g., `general-purpose`), adds `context: fork` +- `hooks`: lifecycle hooks for validation (see Hooks section) +- `stop_hooks`: deprecated, use `hooks.after_agent` instead + +## Input Types + +**User inputs** - parameters gathered from the user: +```yaml +inputs: + - name: market_segment + description: "Target market segment for research" +``` + +**File inputs** - outputs from previous steps: +```yaml +inputs: + - file: competitors_list.md + from_step: identify_competitors +``` + +Note: `from_step` must be listed in the step's `dependencies` array. + +## Output Types + +**Simple output** (string): +```yaml +outputs: + - competitors_list.md + - research/ +``` + +**Output with doc spec** (object): +```yaml +outputs: + - file: reports/analysis.md + doc_spec: .deepwork/doc_specs/analysis_report.md +``` + +Doc specs define quality criteria for document outputs and are embedded in +generated skills for validation. + +## Workflows + +Workflows group steps into named sequences. Steps not in any workflow are +"standalone" and can be run independently. + +```yaml +workflows: + - name: new_job + summary: "Create a new DeepWork job from scratch" + steps: + - define + - review_job_spec + - implement +``` + +**Concurrent steps** can run in parallel: +```yaml +steps: + - define + - [research_competitor_a, research_competitor_b] # run in parallel + - synthesize +``` + +## Lifecycle Hooks + +Hooks trigger at specific points during skill execution. + +**Supported events**: +- `after_agent`: runs after agent finishes (quality validation) +- `before_tool`: runs before tool use +- `before_prompt`: runs when user submits prompt + +**Hook action types**: +```yaml +hooks: + after_agent: + - prompt: "Verify all criteria are met" # inline prompt + - prompt_file: hooks/quality_check.md # prompt from file + - script: hooks/run_tests.sh # shell script +``` + +Note: Claude Code currently only supports script hooks. Prompt hooks are +parsed but not executed (documented limitation). + +## Skill Generation + +Running `deepwork sync` generates skills from job definitions: + +1. Parses all `job.yml` files in `.deepwork/jobs/` +2. For each job, generates a **meta-skill** (entry point) and **step skills** +3. Writes to platform-specific directories (e.g., `.claude/skills/`) + +**Claude Code skill structure**: +- Meta-skill: `.claude/skills/[job_name]/SKILL.md` +- Step skill: `.claude/skills/[job_name].[step_id]/SKILL.md` + +**Gemini CLI skill structure**: +- Meta-skill: `.gemini/skills/[job_name]/index.toml` +- Step skill: `.gemini/skills/[job_name]/[step_id].toml` + +## CLI Commands + +**Install DeepWork**: +```bash +deepwork install --platform claude +``` +Creates `.deepwork/` structure, copies standard jobs, runs sync. + +**Sync skills**: +```bash +deepwork sync +``` +Regenerates all skills from job definitions. + +**Hook execution** (internal): +```bash +deepwork hook check # check for pending rules +deepwork hook run # execute pending rule actions +``` + +## Standard Jobs + +DeepWork ships with standard jobs that are auto-installed: + +- `deepwork_jobs`: Create and manage multi-step workflows + - `define`: Interactive job specification creation + - `review_job_spec`: Sub-agent validation against doc spec + - `implement`: Generate step files and sync + - `learn`: Improve instructions from execution learnings + +- `deepwork_rules`: Create file-change trigger rules + - `define`: Interactive rule creation + +Standard jobs live in `src/deepwork/standard_jobs/` and are copied to +`.deepwork/jobs/` during installation. + +## Writing Step Instructions + +Step instruction files should include: + +1. **Objective**: Clear statement of what this step accomplishes +2. **Task**: Detailed process with numbered steps +3. **Inputs section**: What to gather/read before starting +4. **Output format**: Examples of expected outputs +5. **Quality criteria**: How to verify the step is complete + +Use the phrase "ask structured questions" when gathering user input - +this triggers proper tooling for interactive prompts. + +## Template System + +Skills are generated using Jinja2 templates in `src/deepwork/templates/`: + +- `claude/skill-job-meta.md.jinja`: Meta-skill template +- `claude/skill-job-step.md.jinja`: Step skill template +- `gemini/skill-job-meta.toml.jinja`: Gemini meta-skill +- `gemini/skill-job-step.toml.jinja`: Gemini step skill + +Template variables include job context, step metadata, inputs, outputs, +hooks, quality criteria, and workflow position. + +## Platform Adapters + +The `AgentAdapter` class abstracts platform differences: + +- `ClaudeAdapter`: Claude Code with markdown skills in `.claude/skills/` +- `GeminiAdapter`: Gemini CLI with TOML skills in `.gemini/skills/` + +Adapters handle: +- Skill filename patterns +- Hook event name mapping (e.g., `after_agent` -> `Stop` for Claude) +- Settings file management +- Permission syncing + +## Parser Dataclasses + +The `parser.py` module defines the job structure: + +- `JobDefinition`: Top-level job with name, version, steps, workflows +- `Step`: Individual step with inputs, outputs, hooks, dependencies +- `StepInput`: User parameter or file input +- `OutputSpec`: Output file optionally with doc_spec reference +- `HookAction`: Hook configuration (prompt, prompt_file, or script) +- `Workflow`: Named step sequence +- `WorkflowStepEntry`: Sequential or concurrent step group + +## Validation Rules + +The parser validates: +- Dependencies reference existing steps +- No circular dependencies +- File inputs reference steps in dependencies +- Workflow steps exist +- No duplicate workflow names +- Doc spec files exist (when referenced) + +## Common Patterns + +**Creating a new job**: +1. Run `/deepwork_jobs` (or `/deepwork_jobs.define`) +2. Answer structured questions about your workflow +3. Review generated job.yml +4. Run `/deepwork_jobs.implement` to generate step files +5. Run `deepwork sync` to create skills + +**Adding a step to existing job**: +1. Edit `.deepwork/jobs/[job_name]/job.yml` +2. Add step definition with required fields +3. Create instructions file in `steps/` +4. Update workflow if applicable +5. Run `deepwork sync` + +**Debugging sync issues**: +- Check job.yml syntax with a YAML validator +- Verify step IDs match filenames +- Ensure dependencies form valid DAG +- Check instructions files exist + +--- + +## Topics + +Detailed documentation on specific subjects within this domain. + +$(deepwork topics --expert "deepwork-jobs") + +--- + +## Learnings + +Hard-fought insights from real experiences. + +$(deepwork learnings --expert "deepwork-jobs") \ No newline at end of file diff --git a/.deepwork/experts/deepwork_jobs/expert.yml b/.deepwork/experts/deepwork_jobs/expert.yml new file mode 100644 index 00000000..d84fee24 --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/expert.yml @@ -0,0 +1,285 @@ +discovery_description: | + DeepWork Jobs system - defining, implementing, and syncing multi-step AI workflows. + Covers job.yml schema, step instructions, skill generation, hooks, and CLI commands. + +full_expertise: | + # DeepWork Jobs System + + You are an expert on the DeepWork Jobs system - the framework for building + reusable, multi-step AI workflows that integrate with AI coding assistants. + + ## Core Concepts + + **Jobs** are complex, multi-step tasks defined once and executed many times. + Each job consists of: + + - **job.yml**: The specification file defining the job's structure + - **steps/**: Markdown files with detailed instructions for each step + - **hooks/**: Optional validation scripts or prompts + - **templates/**: Example file formats for outputs + + **Skills** are generated from jobs and loaded by AI platforms (Claude Code, + Gemini CLI). Each step becomes a slash command the user can invoke. + + ## Job Definition Structure + + Jobs live in `.deepwork/jobs/[job_name]/`: + + ``` + .deepwork/jobs/ + └── competitive_research/ + ├── job.yml + ├── steps/ + │ ├── identify_competitors.md + │ └── research_competitors.md + ├── hooks/ + │ └── validate_research.sh + └── templates/ + └── competitor_profile.md + ``` + + ## The job.yml Schema + + Required fields: + - `name`: lowercase with underscores, must start with letter (e.g., `competitive_research`) + - `version`: semantic versioning X.Y.Z (e.g., `1.0.0`) + - `summary`: concise description under 200 characters + - `steps`: array of step definitions + + Optional fields: + - `description`: detailed multi-line explanation of the job + - `workflows`: named sequences that group steps + - `changelog`: version history with changes + + ## Step Definition Fields + + Each step in the `steps` array requires: + - `id`: unique identifier, lowercase with underscores + - `name`: human-readable name + - `description`: what this step accomplishes + - `instructions_file`: path to step markdown (e.g., `steps/identify.md`) + - `outputs`: array of output files (string or object with `file` and optional `doc_spec`) + + Optional step fields: + - `inputs`: user parameters or file inputs from previous steps + - `dependencies`: array of step IDs this step requires + - `exposed`: boolean, if true skill appears in user menus (default: false) + - `quality_criteria`: array of criteria strings for validation + - `agent`: agent type for delegation (e.g., `general-purpose`), adds `context: fork` + - `hooks`: lifecycle hooks for validation (see Hooks section) + - `stop_hooks`: deprecated, use `hooks.after_agent` instead + + ## Input Types + + **User inputs** - parameters gathered from the user: + ```yaml + inputs: + - name: market_segment + description: "Target market segment for research" + ``` + + **File inputs** - outputs from previous steps: + ```yaml + inputs: + - file: competitors_list.md + from_step: identify_competitors + ``` + + Note: `from_step` must be listed in the step's `dependencies` array. + + ## Output Types + + **Simple output** (string): + ```yaml + outputs: + - competitors_list.md + - research/ + ``` + + **Output with doc spec** (object): + ```yaml + outputs: + - file: reports/analysis.md + doc_spec: .deepwork/doc_specs/analysis_report.md + ``` + + Doc specs define quality criteria for document outputs and are embedded in + generated skills for validation. + + ## Workflows + + Workflows group steps into named sequences. Steps not in any workflow are + "standalone" and can be run independently. + + ```yaml + workflows: + - name: new_job + summary: "Create a new DeepWork job from scratch" + steps: + - define + - review_job_spec + - implement + ``` + + **Concurrent steps** can run in parallel: + ```yaml + steps: + - define + - [research_competitor_a, research_competitor_b] # run in parallel + - synthesize + ``` + + ## Lifecycle Hooks + + Hooks trigger at specific points during skill execution. + + **Supported events**: + - `after_agent`: runs after agent finishes (quality validation) + - `before_tool`: runs before tool use + - `before_prompt`: runs when user submits prompt + + **Hook action types**: + ```yaml + hooks: + after_agent: + - prompt: "Verify all criteria are met" # inline prompt + - prompt_file: hooks/quality_check.md # prompt from file + - script: hooks/run_tests.sh # shell script + ``` + + Note: Claude Code currently only supports script hooks. Prompt hooks are + parsed but not executed (documented limitation). + + ## Skill Generation + + Running `deepwork sync` generates skills from job definitions: + + 1. Parses all `job.yml` files in `.deepwork/jobs/` + 2. For each job, generates a **meta-skill** (entry point) and **step skills** + 3. Writes to platform-specific directories (e.g., `.claude/skills/`) + + **Claude Code skill structure**: + - Meta-skill: `.claude/skills/[job_name]/SKILL.md` + - Step skill: `.claude/skills/[job_name].[step_id]/SKILL.md` + + **Gemini CLI skill structure**: + - Meta-skill: `.gemini/skills/[job_name]/index.toml` + - Step skill: `.gemini/skills/[job_name]/[step_id].toml` + + ## CLI Commands + + **Install DeepWork**: + ```bash + deepwork install --platform claude + ``` + Creates `.deepwork/` structure, copies standard jobs, runs sync. + + **Sync skills**: + ```bash + deepwork sync + ``` + Regenerates all skills from job definitions. + + **Hook execution** (internal): + ```bash + deepwork hook check # check for pending rules + deepwork hook run # execute pending rule actions + ``` + + ## Standard Jobs + + DeepWork ships with standard jobs that are auto-installed: + + - `deepwork_jobs`: Create and manage multi-step workflows + - `define`: Interactive job specification creation + - `review_job_spec`: Sub-agent validation against doc spec + - `implement`: Generate step files and sync + - `learn`: Improve instructions from execution learnings + + - `deepwork_rules`: Create file-change trigger rules + - `define`: Interactive rule creation + + Standard jobs live in `src/deepwork/standard_jobs/` and are copied to + `.deepwork/jobs/` during installation. + + ## Writing Step Instructions + + Step instruction files should include: + + 1. **Objective**: Clear statement of what this step accomplishes + 2. **Task**: Detailed process with numbered steps + 3. **Inputs section**: What to gather/read before starting + 4. **Output format**: Examples of expected outputs + 5. **Quality criteria**: How to verify the step is complete + + Use the phrase "ask structured questions" when gathering user input - + this triggers proper tooling for interactive prompts. + + ## Template System + + Skills are generated using Jinja2 templates in `src/deepwork/templates/`: + + - `claude/skill-job-meta.md.jinja`: Meta-skill template + - `claude/skill-job-step.md.jinja`: Step skill template + - `gemini/skill-job-meta.toml.jinja`: Gemini meta-skill + - `gemini/skill-job-step.toml.jinja`: Gemini step skill + + Template variables include job context, step metadata, inputs, outputs, + hooks, quality criteria, and workflow position. + + ## Platform Adapters + + The `AgentAdapter` class abstracts platform differences: + + - `ClaudeAdapter`: Claude Code with markdown skills in `.claude/skills/` + - `GeminiAdapter`: Gemini CLI with TOML skills in `.gemini/skills/` + + Adapters handle: + - Skill filename patterns + - Hook event name mapping (e.g., `after_agent` -> `Stop` for Claude) + - Settings file management + - Permission syncing + + ## Parser Dataclasses + + The `parser.py` module defines the job structure: + + - `JobDefinition`: Top-level job with name, version, steps, workflows + - `Step`: Individual step with inputs, outputs, hooks, dependencies + - `StepInput`: User parameter or file input + - `OutputSpec`: Output file optionally with doc_spec reference + - `HookAction`: Hook configuration (prompt, prompt_file, or script) + - `Workflow`: Named step sequence + - `WorkflowStepEntry`: Sequential or concurrent step group + + ## Validation Rules + + The parser validates: + - Dependencies reference existing steps + - No circular dependencies + - File inputs reference steps in dependencies + - Workflow steps exist + - No duplicate workflow names + - Doc spec files exist (when referenced) + + ## Common Patterns + + **Creating a new job**: + 1. Run `/deepwork_jobs` (or `/deepwork_jobs.define`) + 2. Answer structured questions about your workflow + 3. Review generated job.yml + 4. Run `/deepwork_jobs.implement` to generate step files + 5. Run `deepwork sync` to create skills + + **Adding a step to existing job**: + 1. Edit `.deepwork/jobs/[job_name]/job.yml` + 2. Add step definition with required fields + 3. Create instructions file in `steps/` + 4. Update workflow if applicable + 5. Run `deepwork sync` + + **Debugging sync issues**: + - Check job.yml syntax with a YAML validator + - Verify step IDs match filenames + - Ensure dependencies form valid DAG + - Check instructions files exist diff --git a/.deepwork/experts/deepwork_jobs/learnings/.gitkeep b/.deepwork/experts/deepwork_jobs/learnings/.gitkeep new file mode 100644 index 00000000..8c629330 --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/learnings/.gitkeep @@ -0,0 +1 @@ +# This file ensures the learnings directory exists in version control. diff --git a/.deepwork/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md b/.deepwork/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md new file mode 100644 index 00000000..43ae0931 --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md @@ -0,0 +1,50 @@ +--- +name: Prompt Hooks Not Executed in Claude Code +last_updated: 2025-01-30 +summarized_result: | + Claude Code parses but does not execute prompt-based stop hooks. + Only script/command hooks actually run. Use quality_criteria for validation. +--- + +## Context + +When implementing quality validation for job steps, developers often try +to use inline `prompt` or `prompt_file` hooks for validation. + +## Investigation + +Testing revealed that Claude Code's hook system only executes `command` type +hooks in the settings.json hooks configuration. Prompt-based hooks are parsed +by DeepWork but not rendered into the skill's hook frontmatter because they +would not be executed. + +The template code explicitly filters: +```jinja +{%- set script_hooks = event_hooks | selectattr("type", "equalto", "script") | list %} +``` + +## Resolution + +Two recommended approaches for quality validation: + +1. **Use `quality_criteria` field** (preferred): + ```yaml + quality_criteria: + - "Each competitor has description" + - "Sources are cited" + ``` + This generates instructions for sub-agent review, which works reliably. + +2. **Use script hooks** for objective validation: + ```yaml + hooks: + after_agent: + - script: hooks/run_tests.sh + ``` + Scripts actually execute and can fail the step. + +## Key Takeaway + +For subjective quality checks, use the `quality_criteria` field which triggers +sub-agent review. For objective checks (tests, linting), use script hooks. +Avoid prompt hooks until Claude Code supports them. diff --git a/.deepwork/experts/deepwork_jobs/topics/hooks_and_validation.md b/.deepwork/experts/deepwork_jobs/topics/hooks_and_validation.md new file mode 100644 index 00000000..d335dcfb --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/topics/hooks_and_validation.md @@ -0,0 +1,197 @@ +--- +name: Hooks and Validation +keywords: + - hooks + - validation + - quality + - stop_hooks + - lifecycle +last_updated: 2025-01-30 +--- + +# Hooks and Validation + +How to use lifecycle hooks for quality validation in DeepWork jobs. + +## Lifecycle Hook Events + +DeepWork supports three generic hook events: + +| Event | When it fires | Use case | +|-------|---------------|----------| +| `after_agent` | After agent finishes responding | Quality validation, output verification | +| `before_tool` | Before agent uses a tool | Pre-tool checks, validation | +| `before_prompt` | When user submits a prompt | Session setup, context loading | + +## Platform Mapping + +Hooks are mapped to platform-specific event names: + +| Generic | Claude Code | +|---------|-------------| +| `after_agent` | `Stop`, `SubagentStop` | +| `before_tool` | `PreToolUse` | +| `before_prompt` | `UserPromptSubmit` | + +Note: Gemini CLI does not support skill-level hooks (only global hooks). + +## Hook Action Types + +### Inline Prompt + +Best for simple validation criteria: + +```yaml +hooks: + after_agent: + - prompt: | + Verify the output meets these criteria: + 1. Contains at least 5 competitors + 2. Each has a description + 3. Sources are cited +``` + +**Important**: Prompt hooks are currently parsed but NOT executed by Claude Code. +This is a documented limitation. Use script hooks for actual enforcement. + +### Prompt File + +For detailed/reusable criteria: + +```yaml +hooks: + after_agent: + - prompt_file: hooks/quality_check.md +``` + +The prompt file is read and its content is embedded in the generated skill. +Same limitation applies - parsed but not executed. + +### Script Hook + +For programmatic validation (actually executed): + +```yaml +hooks: + after_agent: + - script: hooks/run_tests.sh +``` + +Scripts are shell scripts that can: +- Run test suites +- Lint output files +- Check for required content +- Validate file formats + +Exit code 0 = pass, non-zero = fail. + +## Script Hook Example + +Create `.deepwork/jobs/[job_name]/hooks/validate.sh`: + +```bash +#!/bin/bash +# Validate research output + +OUTPUT_FILE="research_notes.md" + +if [ ! -f "$OUTPUT_FILE" ]; then + echo "ERROR: $OUTPUT_FILE not found" + exit 1 +fi + +# Check minimum content +LINES=$(wc -l < "$OUTPUT_FILE") +if [ "$LINES" -lt 50 ]; then + echo "ERROR: Output has only $LINES lines, expected at least 50" + exit 1 +fi + +echo "Validation passed" +exit 0 +``` + +Make it executable: +```bash +chmod +x .deepwork/jobs/[job_name]/hooks/validate.sh +``` + +## Combining Multiple Hooks + +```yaml +hooks: + after_agent: + - script: hooks/lint.sh + - script: hooks/run_tests.sh + - prompt: "Verify documentation is complete" +``` + +Hooks run in order. Script hooks are executed; prompt hooks are for reference. + +## Deprecated: stop_hooks + +The `stop_hooks` field is deprecated but still supported: + +```yaml +# Old style (deprecated) +stop_hooks: + - script: hooks/validate.sh + +# New style (preferred) +hooks: + after_agent: + - script: hooks/validate.sh +``` + +Internally, `stop_hooks` are merged into `hooks.after_agent`. + +## Quality Criteria Alternative + +For simple validation, use declarative `quality_criteria` instead of hooks: + +```yaml +steps: + - id: research + quality_criteria: + - "**Data Coverage**: Each competitor has at least 3 data points" + - "**Source Attribution**: All facts are cited" + - "**Relevance**: All competitors are in the target market" +``` + +Quality criteria are rendered in the skill with instructions to use a +sub-agent (Haiku model) for review: + +1. Agent completes work +2. Spawns sub-agent to review against criteria +3. Fixes any issues identified +4. Repeats until sub-agent confirms all criteria pass + +This is the recommended approach for most validation needs - it's more +flexible than scripts and actually works with Claude Code. + +## When to Use Each Approach + +| Approach | When to use | +|----------|-------------| +| `quality_criteria` | Most cases - subjective quality checks | +| Script hooks | Objective checks (tests, linting, format validation) | +| Prompt hooks | Documentation only (not currently executed) | + +## Generated Skill Output + +For script hooks, the generated skill includes: + +```yaml +hooks: + Stop: + - hooks: + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" + SubagentStop: + - hooks: + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" +``` + +Both `Stop` and `SubagentStop` are registered so hooks fire for both +the main agent and any sub-agents. diff --git a/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md b/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md new file mode 100644 index 00000000..657e486e --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md @@ -0,0 +1,153 @@ +--- +name: job.yml Schema Reference +keywords: + - schema + - yaml + - validation + - fields + - structure +last_updated: 2025-01-30 +--- + +# job.yml Schema Reference + +Complete reference for the job.yml specification file. + +## Required Fields + +### name +- Type: string +- Pattern: `^[a-z][a-z0-9_]*$` +- Must start with lowercase letter, can contain lowercase letters, numbers, underscores +- Examples: `competitive_research`, `monthly_report`, `feature_dev` + +### version +- Type: string +- Pattern: `^\d+\.\d+\.\d+$` +- Semantic versioning format +- Examples: `1.0.0`, `2.1.3` + +### summary +- Type: string +- Length: 1-200 characters +- Brief one-line description of the job +- Used in skill descriptions and menus + +### steps +- Type: array +- Minimum items: 1 +- Each item is a step definition object + +## Optional Fields + +### description +- Type: string +- Multi-line detailed explanation +- Included in generated skill files for context +- Good for: problem solved, process overview, target users + +### workflows +- Type: array +- Named sequences grouping steps +- See Workflow Schema section + +### changelog +- Type: array +- Version history entries +- Each entry has `version` (string) and `changes` (string) + +## Step Schema + +### Required Step Fields + +```yaml +steps: + - id: identify_competitors # unique, lowercase_underscores + name: "Identify Competitors" # human-readable + description: "Find and list..." # what it does + instructions_file: steps/identify.md # path to instructions + outputs: # at least one output + - competitors_list.md +``` + +### Optional Step Fields + +```yaml + - id: research + # ... required fields ... + inputs: + - name: market_segment + description: "Target market" + - file: competitors_list.md + from_step: identify_competitors + dependencies: + - identify_competitors + exposed: true # show in user menus + quality_criteria: + - "All competitors have descriptions" + - "Sources are cited" + agent: general-purpose # delegate to agent type + hooks: + after_agent: + - script: hooks/validate.sh +``` + +## Output Formats + +Simple string: +```yaml +outputs: + - report.md + - data/ +``` + +With doc spec: +```yaml +outputs: + - file: reports/analysis.md + doc_spec: .deepwork/doc_specs/analysis.md +``` + +Doc spec path must match pattern: `^\.deepwork/doc_specs/[a-z][a-z0-9_-]*\.md$` + +## Workflow Schema + +```yaml +workflows: + - name: full_analysis + summary: "Complete competitive analysis workflow" + steps: + - identify + - research + - analyze + - report +``` + +Concurrent steps: +```yaml +steps: + - identify + - [research_a, research_b] # parallel execution + - synthesize +``` + +## Hook Schema + +```yaml +hooks: + after_agent: + - prompt: "Verify criteria are met" # inline + - prompt_file: hooks/check.md # from file + - script: hooks/run_tests.sh # shell script +``` + +Each hook action must have exactly one of: `prompt`, `prompt_file`, or `script`. + +## Validation Rules + +1. Step IDs must be unique within the job +2. Dependencies must reference existing step IDs +3. File inputs with `from_step` must have that step in dependencies +4. No circular dependencies allowed +5. Workflow steps must reference existing step IDs +6. No duplicate steps within a workflow diff --git a/.deepwork/experts/deepwork_jobs/topics/skill_generation.md b/.deepwork/experts/deepwork_jobs/topics/skill_generation.md new file mode 100644 index 00000000..9f210b80 --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/topics/skill_generation.md @@ -0,0 +1,155 @@ +--- +name: Skill Generation +keywords: + - sync + - templates + - jinja + - skills + - commands +last_updated: 2025-01-30 +--- + +# Skill Generation + +How DeepWork generates platform-specific skills from job definitions. + +## The Sync Process + +Running `deepwork sync`: + +1. Loads `config.yml` to get configured platforms +2. Discovers all job directories in `.deepwork/jobs/` +3. Parses each `job.yml` into `JobDefinition` dataclass +4. For each job and platform, generates skills using Jinja2 templates +5. Writes skill files to platform-specific directories +6. Syncs hooks and permissions to platform settings + +## Generated Skill Types + +### Meta-Skill (Job Entry Point) +- One per job +- Routes user intent to appropriate step +- Lists available workflows and standalone skills +- Claude: `.claude/skills/[job_name]/SKILL.md` +- Gemini: `.gemini/skills/[job_name]/index.toml` + +### Step Skills +- One per step +- Contains full instructions, inputs, outputs +- Includes workflow position and navigation +- Claude: `.claude/skills/[job_name].[step_id]/SKILL.md` +- Gemini: `.gemini/skills/[job_name]/[step_id].toml` + +## Template Variables + +Templates receive rich context including: + +**Job Context**: +- `job_name`, `job_version`, `job_summary`, `job_description` +- `total_steps`, `has_workflows`, `workflows`, `standalone_steps` + +**Step Context**: +- `step_id`, `step_name`, `step_description`, `step_number` +- `instructions_content` (full markdown from instructions file) +- `user_inputs`, `file_inputs`, `outputs`, `dependencies` +- `is_standalone`, `exposed`, `agent` + +**Workflow Context** (when step is in workflow): +- `workflow_name`, `workflow_summary` +- `workflow_step_number`, `workflow_total_steps` +- `workflow_next_step`, `workflow_prev_step` + +**Quality & Hooks**: +- `quality_criteria` (array of strings) +- `hooks` (dict by platform event name) +- `stop_hooks` (backward compat: after_agent hooks) + +## Template Location + +Templates live in `src/deepwork/templates/[platform]/`: + +``` +templates/ +├── claude/ +│ ├── skill-job-meta.md.jinja +│ ├── skill-job-step.md.jinja +│ └── settings.json +└── gemini/ + ├── skill-job-meta.toml.jinja + └── skill-job-step.toml.jinja +``` + +## Platform Differences + +**Claude Code**: +- Markdown format with YAML frontmatter +- Uses `---` delimited frontmatter for metadata +- Hook events: `Stop`, `SubagentStop`, `PreToolUse`, `UserPromptSubmit` +- Skills directory: `.claude/skills/` + +**Gemini CLI**: +- TOML format +- Uses namespace separators via directories +- No skill-level hooks (global only) +- Skills directory: `.gemini/skills/` + +## The Generator Class + +`SkillGenerator` in `core/generator.py`: + +```python +generator = SkillGenerator() + +# Generate all skills for a job +paths = generator.generate_all_skills( + job=job_definition, + adapter=claude_adapter, + output_dir=project_path, + project_root=project_path +) + +# Generate single step skill +path = generator.generate_step_skill( + job=job_def, + step=step, + adapter=adapter, + output_dir=output_dir +) +``` + +## Doc Spec Integration + +When outputs reference doc specs, the generator: + +1. Loads doc spec file using `DocSpecParser` +2. Extracts quality criteria, target audience, example document +3. Includes this context in template variables +4. Generated skill displays doc spec requirements inline + +## Skill Frontmatter + +Claude skills have YAML frontmatter: + +```yaml +--- +name: job_name.step_id +description: "Step description" +user-invocable: false # when exposed: false +context: fork # when agent is specified +agent: general-purpose +hooks: + Stop: + - hooks: + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" +--- +``` + +## Permissions Syncing + +After generating skills, adapters sync permissions: + +- Base permissions (read `.deepwork/tmp/**`) +- Skill invocation permissions (`Skill(job_name)`, `Skill(job_name.step_id)`) + +Permissions are added to `.claude/settings.json` in the `permissions.allow` array. diff --git a/.deepwork/experts/deepwork_jobs/topics/step_instructions.md b/.deepwork/experts/deepwork_jobs/topics/step_instructions.md new file mode 100644 index 00000000..0c45b0d9 --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/topics/step_instructions.md @@ -0,0 +1,187 @@ +--- +name: Writing Step Instructions +keywords: + - instructions + - steps + - markdown + - writing + - best practices +last_updated: 2025-01-30 +--- + +# Writing Step Instructions + +Best practices for writing effective step instruction files. + +## File Location + +Step instructions live in `.deepwork/jobs/[job_name]/steps/[step_id].md`. + +The path is specified in job.yml via `instructions_file`: +```yaml +steps: + - id: identify_competitors + instructions_file: steps/identify_competitors.md +``` + +## Recommended Structure + +### 1. Objective Section + +Start with a clear objective statement: + +```markdown +## Objective + +Create a comprehensive list of competitors in the target market by +systematically researching industry players and their offerings. +``` + +### 2. Task Section + +Detailed step-by-step process: + +```markdown +## Task + +### Step 1: Understand the Market + +Ask structured questions to gather context: +- What industry or market segment? +- What product category? +- Geographic scope? + +### Step 2: Research Sources + +Search for competitors using: +1. Industry databases and reports +2. Google searches for market leaders +3. Customer review sites +... +``` + +### 3. Input Handling + +If the step has user inputs, explicitly request them: + +```markdown +## Inputs + +Before proceeding, gather the following from the user: +- **market_segment**: Target market for analysis +- **product_category**: Specific product/service category + +Use the AskUserQuestion tool to collect these inputs. +``` + +### 4. Output Format + +Show what good output looks like: + +```markdown +## Output Format + +Create `competitors_list.md` with the following structure: + +```markdown +# Competitors List + +## Market: [market_segment] + +### Competitor 1: Acme Corp +- **Website**: acme.com +- **Description**: Brief overview +- **Key Products**: Product A, Product B +``` + +### 5. Quality Criteria + +Define how to verify the step is complete: + +```markdown +## Quality Criteria + +- At least 5 competitors identified +- Each competitor has description and key products +- Sources are cited for all information +- List is relevant to the specified market +``` + +## Key Phrases + +### "Ask structured questions" + +When gathering user input, always use this phrase: + +```markdown +Ask structured questions to understand the user's requirements: +1. What is your target market? +2. Who are your main competitors? +``` + +This phrase triggers the AskUserQuestion tool which provides a better +user experience with clear options. + +### "Use the Skill tool to invoke" + +For workflow continuation: + +```markdown +## On Completion + +1. Verify outputs are created +2. Use the Skill tool to invoke `/job_name.next_step` +``` + +## Supplementary Files + +Place additional reference materials in `steps/`: + +``` +steps/ +├── identify_competitors.md +├── research_competitors.md +└── competitor_template.md # supplementary reference +``` + +Reference them using full paths: +```markdown +Use the template in `.deepwork/jobs/competitive_research/steps/competitor_template.md` +to structure each competitor profile. +``` + +## Anti-Patterns to Avoid + +### Vague Instructions +Bad: "Research the competitors" +Good: "Search each competitor's website, LinkedIn, and review sites to gather..." + +### Missing Outputs +Bad: "Create a report" +Good: "Create `research_notes.md` with sections for each competitor..." + +### Skipping Inputs +Bad: Assume inputs are available +Good: "Read `competitors_list.md` from the previous step. If it doesn't exist..." + +### Generic Quality Criteria +Bad: "Output should be good quality" +Good: "Each competitor profile includes at least 3 data points with sources" + +## Instruction Length + +- Keep instructions focused and actionable +- Aim for 1-3 pages of content +- Extract lengthy examples into separate template files +- Use bullet points over paragraphs where appropriate + +## Variables in Instructions + +Instructions can reference job-level context. The generated skill includes: +- Job name and description +- Step position in workflow +- Dependencies and next steps +- All inputs and outputs + +You don't need to repeat this metadata in instructions - it's included +automatically in the generated skill. diff --git a/src/deepwork/standard/experts/deepwork_jobs/expert.yml b/src/deepwork/standard/experts/deepwork_jobs/expert.yml new file mode 100644 index 00000000..d84fee24 --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/expert.yml @@ -0,0 +1,285 @@ +discovery_description: | + DeepWork Jobs system - defining, implementing, and syncing multi-step AI workflows. + Covers job.yml schema, step instructions, skill generation, hooks, and CLI commands. + +full_expertise: | + # DeepWork Jobs System + + You are an expert on the DeepWork Jobs system - the framework for building + reusable, multi-step AI workflows that integrate with AI coding assistants. + + ## Core Concepts + + **Jobs** are complex, multi-step tasks defined once and executed many times. + Each job consists of: + + - **job.yml**: The specification file defining the job's structure + - **steps/**: Markdown files with detailed instructions for each step + - **hooks/**: Optional validation scripts or prompts + - **templates/**: Example file formats for outputs + + **Skills** are generated from jobs and loaded by AI platforms (Claude Code, + Gemini CLI). Each step becomes a slash command the user can invoke. + + ## Job Definition Structure + + Jobs live in `.deepwork/jobs/[job_name]/`: + + ``` + .deepwork/jobs/ + └── competitive_research/ + ├── job.yml + ├── steps/ + │ ├── identify_competitors.md + │ └── research_competitors.md + ├── hooks/ + │ └── validate_research.sh + └── templates/ + └── competitor_profile.md + ``` + + ## The job.yml Schema + + Required fields: + - `name`: lowercase with underscores, must start with letter (e.g., `competitive_research`) + - `version`: semantic versioning X.Y.Z (e.g., `1.0.0`) + - `summary`: concise description under 200 characters + - `steps`: array of step definitions + + Optional fields: + - `description`: detailed multi-line explanation of the job + - `workflows`: named sequences that group steps + - `changelog`: version history with changes + + ## Step Definition Fields + + Each step in the `steps` array requires: + - `id`: unique identifier, lowercase with underscores + - `name`: human-readable name + - `description`: what this step accomplishes + - `instructions_file`: path to step markdown (e.g., `steps/identify.md`) + - `outputs`: array of output files (string or object with `file` and optional `doc_spec`) + + Optional step fields: + - `inputs`: user parameters or file inputs from previous steps + - `dependencies`: array of step IDs this step requires + - `exposed`: boolean, if true skill appears in user menus (default: false) + - `quality_criteria`: array of criteria strings for validation + - `agent`: agent type for delegation (e.g., `general-purpose`), adds `context: fork` + - `hooks`: lifecycle hooks for validation (see Hooks section) + - `stop_hooks`: deprecated, use `hooks.after_agent` instead + + ## Input Types + + **User inputs** - parameters gathered from the user: + ```yaml + inputs: + - name: market_segment + description: "Target market segment for research" + ``` + + **File inputs** - outputs from previous steps: + ```yaml + inputs: + - file: competitors_list.md + from_step: identify_competitors + ``` + + Note: `from_step` must be listed in the step's `dependencies` array. + + ## Output Types + + **Simple output** (string): + ```yaml + outputs: + - competitors_list.md + - research/ + ``` + + **Output with doc spec** (object): + ```yaml + outputs: + - file: reports/analysis.md + doc_spec: .deepwork/doc_specs/analysis_report.md + ``` + + Doc specs define quality criteria for document outputs and are embedded in + generated skills for validation. + + ## Workflows + + Workflows group steps into named sequences. Steps not in any workflow are + "standalone" and can be run independently. + + ```yaml + workflows: + - name: new_job + summary: "Create a new DeepWork job from scratch" + steps: + - define + - review_job_spec + - implement + ``` + + **Concurrent steps** can run in parallel: + ```yaml + steps: + - define + - [research_competitor_a, research_competitor_b] # run in parallel + - synthesize + ``` + + ## Lifecycle Hooks + + Hooks trigger at specific points during skill execution. + + **Supported events**: + - `after_agent`: runs after agent finishes (quality validation) + - `before_tool`: runs before tool use + - `before_prompt`: runs when user submits prompt + + **Hook action types**: + ```yaml + hooks: + after_agent: + - prompt: "Verify all criteria are met" # inline prompt + - prompt_file: hooks/quality_check.md # prompt from file + - script: hooks/run_tests.sh # shell script + ``` + + Note: Claude Code currently only supports script hooks. Prompt hooks are + parsed but not executed (documented limitation). + + ## Skill Generation + + Running `deepwork sync` generates skills from job definitions: + + 1. Parses all `job.yml` files in `.deepwork/jobs/` + 2. For each job, generates a **meta-skill** (entry point) and **step skills** + 3. Writes to platform-specific directories (e.g., `.claude/skills/`) + + **Claude Code skill structure**: + - Meta-skill: `.claude/skills/[job_name]/SKILL.md` + - Step skill: `.claude/skills/[job_name].[step_id]/SKILL.md` + + **Gemini CLI skill structure**: + - Meta-skill: `.gemini/skills/[job_name]/index.toml` + - Step skill: `.gemini/skills/[job_name]/[step_id].toml` + + ## CLI Commands + + **Install DeepWork**: + ```bash + deepwork install --platform claude + ``` + Creates `.deepwork/` structure, copies standard jobs, runs sync. + + **Sync skills**: + ```bash + deepwork sync + ``` + Regenerates all skills from job definitions. + + **Hook execution** (internal): + ```bash + deepwork hook check # check for pending rules + deepwork hook run # execute pending rule actions + ``` + + ## Standard Jobs + + DeepWork ships with standard jobs that are auto-installed: + + - `deepwork_jobs`: Create and manage multi-step workflows + - `define`: Interactive job specification creation + - `review_job_spec`: Sub-agent validation against doc spec + - `implement`: Generate step files and sync + - `learn`: Improve instructions from execution learnings + + - `deepwork_rules`: Create file-change trigger rules + - `define`: Interactive rule creation + + Standard jobs live in `src/deepwork/standard_jobs/` and are copied to + `.deepwork/jobs/` during installation. + + ## Writing Step Instructions + + Step instruction files should include: + + 1. **Objective**: Clear statement of what this step accomplishes + 2. **Task**: Detailed process with numbered steps + 3. **Inputs section**: What to gather/read before starting + 4. **Output format**: Examples of expected outputs + 5. **Quality criteria**: How to verify the step is complete + + Use the phrase "ask structured questions" when gathering user input - + this triggers proper tooling for interactive prompts. + + ## Template System + + Skills are generated using Jinja2 templates in `src/deepwork/templates/`: + + - `claude/skill-job-meta.md.jinja`: Meta-skill template + - `claude/skill-job-step.md.jinja`: Step skill template + - `gemini/skill-job-meta.toml.jinja`: Gemini meta-skill + - `gemini/skill-job-step.toml.jinja`: Gemini step skill + + Template variables include job context, step metadata, inputs, outputs, + hooks, quality criteria, and workflow position. + + ## Platform Adapters + + The `AgentAdapter` class abstracts platform differences: + + - `ClaudeAdapter`: Claude Code with markdown skills in `.claude/skills/` + - `GeminiAdapter`: Gemini CLI with TOML skills in `.gemini/skills/` + + Adapters handle: + - Skill filename patterns + - Hook event name mapping (e.g., `after_agent` -> `Stop` for Claude) + - Settings file management + - Permission syncing + + ## Parser Dataclasses + + The `parser.py` module defines the job structure: + + - `JobDefinition`: Top-level job with name, version, steps, workflows + - `Step`: Individual step with inputs, outputs, hooks, dependencies + - `StepInput`: User parameter or file input + - `OutputSpec`: Output file optionally with doc_spec reference + - `HookAction`: Hook configuration (prompt, prompt_file, or script) + - `Workflow`: Named step sequence + - `WorkflowStepEntry`: Sequential or concurrent step group + + ## Validation Rules + + The parser validates: + - Dependencies reference existing steps + - No circular dependencies + - File inputs reference steps in dependencies + - Workflow steps exist + - No duplicate workflow names + - Doc spec files exist (when referenced) + + ## Common Patterns + + **Creating a new job**: + 1. Run `/deepwork_jobs` (or `/deepwork_jobs.define`) + 2. Answer structured questions about your workflow + 3. Review generated job.yml + 4. Run `/deepwork_jobs.implement` to generate step files + 5. Run `deepwork sync` to create skills + + **Adding a step to existing job**: + 1. Edit `.deepwork/jobs/[job_name]/job.yml` + 2. Add step definition with required fields + 3. Create instructions file in `steps/` + 4. Update workflow if applicable + 5. Run `deepwork sync` + + **Debugging sync issues**: + - Check job.yml syntax with a YAML validator + - Verify step IDs match filenames + - Ensure dependencies form valid DAG + - Check instructions files exist diff --git a/src/deepwork/standard/experts/deepwork_jobs/learnings/.gitkeep b/src/deepwork/standard/experts/deepwork_jobs/learnings/.gitkeep new file mode 100644 index 00000000..8c629330 --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/learnings/.gitkeep @@ -0,0 +1 @@ +# This file ensures the learnings directory exists in version control. diff --git a/src/deepwork/standard/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md b/src/deepwork/standard/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md new file mode 100644 index 00000000..43ae0931 --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/learnings/prompt_hooks_not_executed.md @@ -0,0 +1,50 @@ +--- +name: Prompt Hooks Not Executed in Claude Code +last_updated: 2025-01-30 +summarized_result: | + Claude Code parses but does not execute prompt-based stop hooks. + Only script/command hooks actually run. Use quality_criteria for validation. +--- + +## Context + +When implementing quality validation for job steps, developers often try +to use inline `prompt` or `prompt_file` hooks for validation. + +## Investigation + +Testing revealed that Claude Code's hook system only executes `command` type +hooks in the settings.json hooks configuration. Prompt-based hooks are parsed +by DeepWork but not rendered into the skill's hook frontmatter because they +would not be executed. + +The template code explicitly filters: +```jinja +{%- set script_hooks = event_hooks | selectattr("type", "equalto", "script") | list %} +``` + +## Resolution + +Two recommended approaches for quality validation: + +1. **Use `quality_criteria` field** (preferred): + ```yaml + quality_criteria: + - "Each competitor has description" + - "Sources are cited" + ``` + This generates instructions for sub-agent review, which works reliably. + +2. **Use script hooks** for objective validation: + ```yaml + hooks: + after_agent: + - script: hooks/run_tests.sh + ``` + Scripts actually execute and can fail the step. + +## Key Takeaway + +For subjective quality checks, use the `quality_criteria` field which triggers +sub-agent review. For objective checks (tests, linting), use script hooks. +Avoid prompt hooks until Claude Code supports them. diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/hooks_and_validation.md b/src/deepwork/standard/experts/deepwork_jobs/topics/hooks_and_validation.md new file mode 100644 index 00000000..d335dcfb --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/hooks_and_validation.md @@ -0,0 +1,197 @@ +--- +name: Hooks and Validation +keywords: + - hooks + - validation + - quality + - stop_hooks + - lifecycle +last_updated: 2025-01-30 +--- + +# Hooks and Validation + +How to use lifecycle hooks for quality validation in DeepWork jobs. + +## Lifecycle Hook Events + +DeepWork supports three generic hook events: + +| Event | When it fires | Use case | +|-------|---------------|----------| +| `after_agent` | After agent finishes responding | Quality validation, output verification | +| `before_tool` | Before agent uses a tool | Pre-tool checks, validation | +| `before_prompt` | When user submits a prompt | Session setup, context loading | + +## Platform Mapping + +Hooks are mapped to platform-specific event names: + +| Generic | Claude Code | +|---------|-------------| +| `after_agent` | `Stop`, `SubagentStop` | +| `before_tool` | `PreToolUse` | +| `before_prompt` | `UserPromptSubmit` | + +Note: Gemini CLI does not support skill-level hooks (only global hooks). + +## Hook Action Types + +### Inline Prompt + +Best for simple validation criteria: + +```yaml +hooks: + after_agent: + - prompt: | + Verify the output meets these criteria: + 1. Contains at least 5 competitors + 2. Each has a description + 3. Sources are cited +``` + +**Important**: Prompt hooks are currently parsed but NOT executed by Claude Code. +This is a documented limitation. Use script hooks for actual enforcement. + +### Prompt File + +For detailed/reusable criteria: + +```yaml +hooks: + after_agent: + - prompt_file: hooks/quality_check.md +``` + +The prompt file is read and its content is embedded in the generated skill. +Same limitation applies - parsed but not executed. + +### Script Hook + +For programmatic validation (actually executed): + +```yaml +hooks: + after_agent: + - script: hooks/run_tests.sh +``` + +Scripts are shell scripts that can: +- Run test suites +- Lint output files +- Check for required content +- Validate file formats + +Exit code 0 = pass, non-zero = fail. + +## Script Hook Example + +Create `.deepwork/jobs/[job_name]/hooks/validate.sh`: + +```bash +#!/bin/bash +# Validate research output + +OUTPUT_FILE="research_notes.md" + +if [ ! -f "$OUTPUT_FILE" ]; then + echo "ERROR: $OUTPUT_FILE not found" + exit 1 +fi + +# Check minimum content +LINES=$(wc -l < "$OUTPUT_FILE") +if [ "$LINES" -lt 50 ]; then + echo "ERROR: Output has only $LINES lines, expected at least 50" + exit 1 +fi + +echo "Validation passed" +exit 0 +``` + +Make it executable: +```bash +chmod +x .deepwork/jobs/[job_name]/hooks/validate.sh +``` + +## Combining Multiple Hooks + +```yaml +hooks: + after_agent: + - script: hooks/lint.sh + - script: hooks/run_tests.sh + - prompt: "Verify documentation is complete" +``` + +Hooks run in order. Script hooks are executed; prompt hooks are for reference. + +## Deprecated: stop_hooks + +The `stop_hooks` field is deprecated but still supported: + +```yaml +# Old style (deprecated) +stop_hooks: + - script: hooks/validate.sh + +# New style (preferred) +hooks: + after_agent: + - script: hooks/validate.sh +``` + +Internally, `stop_hooks` are merged into `hooks.after_agent`. + +## Quality Criteria Alternative + +For simple validation, use declarative `quality_criteria` instead of hooks: + +```yaml +steps: + - id: research + quality_criteria: + - "**Data Coverage**: Each competitor has at least 3 data points" + - "**Source Attribution**: All facts are cited" + - "**Relevance**: All competitors are in the target market" +``` + +Quality criteria are rendered in the skill with instructions to use a +sub-agent (Haiku model) for review: + +1. Agent completes work +2. Spawns sub-agent to review against criteria +3. Fixes any issues identified +4. Repeats until sub-agent confirms all criteria pass + +This is the recommended approach for most validation needs - it's more +flexible than scripts and actually works with Claude Code. + +## When to Use Each Approach + +| Approach | When to use | +|----------|-------------| +| `quality_criteria` | Most cases - subjective quality checks | +| Script hooks | Objective checks (tests, linting, format validation) | +| Prompt hooks | Documentation only (not currently executed) | + +## Generated Skill Output + +For script hooks, the generated skill includes: + +```yaml +hooks: + Stop: + - hooks: + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" + SubagentStop: + - hooks: + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" +``` + +Both `Stop` and `SubagentStop` are registered so hooks fire for both +the main agent and any sub-agents. diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md b/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md new file mode 100644 index 00000000..657e486e --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md @@ -0,0 +1,153 @@ +--- +name: job.yml Schema Reference +keywords: + - schema + - yaml + - validation + - fields + - structure +last_updated: 2025-01-30 +--- + +# job.yml Schema Reference + +Complete reference for the job.yml specification file. + +## Required Fields + +### name +- Type: string +- Pattern: `^[a-z][a-z0-9_]*$` +- Must start with lowercase letter, can contain lowercase letters, numbers, underscores +- Examples: `competitive_research`, `monthly_report`, `feature_dev` + +### version +- Type: string +- Pattern: `^\d+\.\d+\.\d+$` +- Semantic versioning format +- Examples: `1.0.0`, `2.1.3` + +### summary +- Type: string +- Length: 1-200 characters +- Brief one-line description of the job +- Used in skill descriptions and menus + +### steps +- Type: array +- Minimum items: 1 +- Each item is a step definition object + +## Optional Fields + +### description +- Type: string +- Multi-line detailed explanation +- Included in generated skill files for context +- Good for: problem solved, process overview, target users + +### workflows +- Type: array +- Named sequences grouping steps +- See Workflow Schema section + +### changelog +- Type: array +- Version history entries +- Each entry has `version` (string) and `changes` (string) + +## Step Schema + +### Required Step Fields + +```yaml +steps: + - id: identify_competitors # unique, lowercase_underscores + name: "Identify Competitors" # human-readable + description: "Find and list..." # what it does + instructions_file: steps/identify.md # path to instructions + outputs: # at least one output + - competitors_list.md +``` + +### Optional Step Fields + +```yaml + - id: research + # ... required fields ... + inputs: + - name: market_segment + description: "Target market" + - file: competitors_list.md + from_step: identify_competitors + dependencies: + - identify_competitors + exposed: true # show in user menus + quality_criteria: + - "All competitors have descriptions" + - "Sources are cited" + agent: general-purpose # delegate to agent type + hooks: + after_agent: + - script: hooks/validate.sh +``` + +## Output Formats + +Simple string: +```yaml +outputs: + - report.md + - data/ +``` + +With doc spec: +```yaml +outputs: + - file: reports/analysis.md + doc_spec: .deepwork/doc_specs/analysis.md +``` + +Doc spec path must match pattern: `^\.deepwork/doc_specs/[a-z][a-z0-9_-]*\.md$` + +## Workflow Schema + +```yaml +workflows: + - name: full_analysis + summary: "Complete competitive analysis workflow" + steps: + - identify + - research + - analyze + - report +``` + +Concurrent steps: +```yaml +steps: + - identify + - [research_a, research_b] # parallel execution + - synthesize +``` + +## Hook Schema + +```yaml +hooks: + after_agent: + - prompt: "Verify criteria are met" # inline + - prompt_file: hooks/check.md # from file + - script: hooks/run_tests.sh # shell script +``` + +Each hook action must have exactly one of: `prompt`, `prompt_file`, or `script`. + +## Validation Rules + +1. Step IDs must be unique within the job +2. Dependencies must reference existing step IDs +3. File inputs with `from_step` must have that step in dependencies +4. No circular dependencies allowed +5. Workflow steps must reference existing step IDs +6. No duplicate steps within a workflow diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/skill_generation.md b/src/deepwork/standard/experts/deepwork_jobs/topics/skill_generation.md new file mode 100644 index 00000000..9f210b80 --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/skill_generation.md @@ -0,0 +1,155 @@ +--- +name: Skill Generation +keywords: + - sync + - templates + - jinja + - skills + - commands +last_updated: 2025-01-30 +--- + +# Skill Generation + +How DeepWork generates platform-specific skills from job definitions. + +## The Sync Process + +Running `deepwork sync`: + +1. Loads `config.yml` to get configured platforms +2. Discovers all job directories in `.deepwork/jobs/` +3. Parses each `job.yml` into `JobDefinition` dataclass +4. For each job and platform, generates skills using Jinja2 templates +5. Writes skill files to platform-specific directories +6. Syncs hooks and permissions to platform settings + +## Generated Skill Types + +### Meta-Skill (Job Entry Point) +- One per job +- Routes user intent to appropriate step +- Lists available workflows and standalone skills +- Claude: `.claude/skills/[job_name]/SKILL.md` +- Gemini: `.gemini/skills/[job_name]/index.toml` + +### Step Skills +- One per step +- Contains full instructions, inputs, outputs +- Includes workflow position and navigation +- Claude: `.claude/skills/[job_name].[step_id]/SKILL.md` +- Gemini: `.gemini/skills/[job_name]/[step_id].toml` + +## Template Variables + +Templates receive rich context including: + +**Job Context**: +- `job_name`, `job_version`, `job_summary`, `job_description` +- `total_steps`, `has_workflows`, `workflows`, `standalone_steps` + +**Step Context**: +- `step_id`, `step_name`, `step_description`, `step_number` +- `instructions_content` (full markdown from instructions file) +- `user_inputs`, `file_inputs`, `outputs`, `dependencies` +- `is_standalone`, `exposed`, `agent` + +**Workflow Context** (when step is in workflow): +- `workflow_name`, `workflow_summary` +- `workflow_step_number`, `workflow_total_steps` +- `workflow_next_step`, `workflow_prev_step` + +**Quality & Hooks**: +- `quality_criteria` (array of strings) +- `hooks` (dict by platform event name) +- `stop_hooks` (backward compat: after_agent hooks) + +## Template Location + +Templates live in `src/deepwork/templates/[platform]/`: + +``` +templates/ +├── claude/ +│ ├── skill-job-meta.md.jinja +│ ├── skill-job-step.md.jinja +│ └── settings.json +└── gemini/ + ├── skill-job-meta.toml.jinja + └── skill-job-step.toml.jinja +``` + +## Platform Differences + +**Claude Code**: +- Markdown format with YAML frontmatter +- Uses `---` delimited frontmatter for metadata +- Hook events: `Stop`, `SubagentStop`, `PreToolUse`, `UserPromptSubmit` +- Skills directory: `.claude/skills/` + +**Gemini CLI**: +- TOML format +- Uses namespace separators via directories +- No skill-level hooks (global only) +- Skills directory: `.gemini/skills/` + +## The Generator Class + +`SkillGenerator` in `core/generator.py`: + +```python +generator = SkillGenerator() + +# Generate all skills for a job +paths = generator.generate_all_skills( + job=job_definition, + adapter=claude_adapter, + output_dir=project_path, + project_root=project_path +) + +# Generate single step skill +path = generator.generate_step_skill( + job=job_def, + step=step, + adapter=adapter, + output_dir=output_dir +) +``` + +## Doc Spec Integration + +When outputs reference doc specs, the generator: + +1. Loads doc spec file using `DocSpecParser` +2. Extracts quality criteria, target audience, example document +3. Includes this context in template variables +4. Generated skill displays doc spec requirements inline + +## Skill Frontmatter + +Claude skills have YAML frontmatter: + +```yaml +--- +name: job_name.step_id +description: "Step description" +user-invocable: false # when exposed: false +context: fork # when agent is specified +agent: general-purpose +hooks: + Stop: + - hooks: + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" +--- +``` + +## Permissions Syncing + +After generating skills, adapters sync permissions: + +- Base permissions (read `.deepwork/tmp/**`) +- Skill invocation permissions (`Skill(job_name)`, `Skill(job_name.step_id)`) + +Permissions are added to `.claude/settings.json` in the `permissions.allow` array. diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md b/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md new file mode 100644 index 00000000..0c45b0d9 --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md @@ -0,0 +1,187 @@ +--- +name: Writing Step Instructions +keywords: + - instructions + - steps + - markdown + - writing + - best practices +last_updated: 2025-01-30 +--- + +# Writing Step Instructions + +Best practices for writing effective step instruction files. + +## File Location + +Step instructions live in `.deepwork/jobs/[job_name]/steps/[step_id].md`. + +The path is specified in job.yml via `instructions_file`: +```yaml +steps: + - id: identify_competitors + instructions_file: steps/identify_competitors.md +``` + +## Recommended Structure + +### 1. Objective Section + +Start with a clear objective statement: + +```markdown +## Objective + +Create a comprehensive list of competitors in the target market by +systematically researching industry players and their offerings. +``` + +### 2. Task Section + +Detailed step-by-step process: + +```markdown +## Task + +### Step 1: Understand the Market + +Ask structured questions to gather context: +- What industry or market segment? +- What product category? +- Geographic scope? + +### Step 2: Research Sources + +Search for competitors using: +1. Industry databases and reports +2. Google searches for market leaders +3. Customer review sites +... +``` + +### 3. Input Handling + +If the step has user inputs, explicitly request them: + +```markdown +## Inputs + +Before proceeding, gather the following from the user: +- **market_segment**: Target market for analysis +- **product_category**: Specific product/service category + +Use the AskUserQuestion tool to collect these inputs. +``` + +### 4. Output Format + +Show what good output looks like: + +```markdown +## Output Format + +Create `competitors_list.md` with the following structure: + +```markdown +# Competitors List + +## Market: [market_segment] + +### Competitor 1: Acme Corp +- **Website**: acme.com +- **Description**: Brief overview +- **Key Products**: Product A, Product B +``` + +### 5. Quality Criteria + +Define how to verify the step is complete: + +```markdown +## Quality Criteria + +- At least 5 competitors identified +- Each competitor has description and key products +- Sources are cited for all information +- List is relevant to the specified market +``` + +## Key Phrases + +### "Ask structured questions" + +When gathering user input, always use this phrase: + +```markdown +Ask structured questions to understand the user's requirements: +1. What is your target market? +2. Who are your main competitors? +``` + +This phrase triggers the AskUserQuestion tool which provides a better +user experience with clear options. + +### "Use the Skill tool to invoke" + +For workflow continuation: + +```markdown +## On Completion + +1. Verify outputs are created +2. Use the Skill tool to invoke `/job_name.next_step` +``` + +## Supplementary Files + +Place additional reference materials in `steps/`: + +``` +steps/ +├── identify_competitors.md +├── research_competitors.md +└── competitor_template.md # supplementary reference +``` + +Reference them using full paths: +```markdown +Use the template in `.deepwork/jobs/competitive_research/steps/competitor_template.md` +to structure each competitor profile. +``` + +## Anti-Patterns to Avoid + +### Vague Instructions +Bad: "Research the competitors" +Good: "Search each competitor's website, LinkedIn, and review sites to gather..." + +### Missing Outputs +Bad: "Create a report" +Good: "Create `research_notes.md` with sections for each competitor..." + +### Skipping Inputs +Bad: Assume inputs are available +Good: "Read `competitors_list.md` from the previous step. If it doesn't exist..." + +### Generic Quality Criteria +Bad: "Output should be good quality" +Good: "Each competitor profile includes at least 3 data points with sources" + +## Instruction Length + +- Keep instructions focused and actionable +- Aim for 1-3 pages of content +- Extract lengthy examples into separate template files +- Use bullet points over paragraphs where appropriate + +## Variables in Instructions + +Instructions can reference job-level context. The generated skill includes: +- Job name and description +- Step position in workflow +- Dependencies and next steps +- All inputs and outputs + +You don't need to repeat this metadata in instructions - it's included +automatically in the generated skill. From 4ff7c6cbff6435b42ef4b18d882ea37b11f30232 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 1 Feb 2026 09:52:25 -0700 Subject: [PATCH 6/9] feat: Add expert delegation to deepwork_jobs steps and improve docs - Add `agent: deepwork-jobs` to all 4 steps in deepwork_jobs job.yml - Remove misleading "Prerequisites" documentation from step files - Create new step_delegation.md topic explaining how to use expert delegation - Update job_yml_schema.md with "Agent Delegation" section - Key insight: "This is how you make a step 'run via' an expert" The deepwork_jobs steps now properly delegate to the deepwork-jobs expert, giving them access to job schema knowledge, best practices, and learnings. Co-Authored-By: Claude Opus 4.5 --- .claude/skills/deepwork_jobs.define/SKILL.md | 457 +++--------------- .../skills/deepwork_jobs.implement/SKILL.md | 237 +++------ .claude/skills/deepwork_jobs.learn/SKILL.md | 377 ++++----------- .../deepwork_jobs.review_job_spec/SKILL.md | 204 ++------ .../deepwork_jobs/topics/job_yml_schema.md | 29 +- .../deepwork_jobs/topics/step_delegation.md | 145 ++++++ .deepwork/jobs/deepwork_jobs/job.yml | 40 +- .deepwork/jobs/deepwork_jobs/steps/define.md | 455 +++-------------- .../jobs/deepwork_jobs/steps/implement.md | 235 +++------ .deepwork/jobs/deepwork_jobs/steps/learn.md | 375 +++----------- .../deepwork_jobs/steps/review_job_spec.md | 202 ++------ .gemini/skills/deepwork_jobs/define.toml | 455 +++-------------- .gemini/skills/deepwork_jobs/implement.toml | 235 +++------ .gemini/skills/deepwork_jobs/learn.toml | 375 +++----------- .../skills/deepwork_jobs/review_job_spec.toml | 202 ++------ .../deepwork_jobs/topics/job_yml_schema.md | 29 +- .../deepwork_jobs/topics/step_delegation.md | 145 ++++++ .../standard_jobs/deepwork_jobs/job.yml | 40 +- .../deepwork_jobs/steps/define.md | 455 +++-------------- .../deepwork_jobs/steps/implement.md | 235 +++------ .../deepwork_jobs/steps/learn.md | 375 +++----------- .../deepwork_jobs/steps/review_job_spec.md | 202 ++------ 22 files changed, 1356 insertions(+), 4148 deletions(-) create mode 100644 .deepwork/experts/deepwork_jobs/topics/step_delegation.md create mode 100644 src/deepwork/standard/experts/deepwork_jobs/topics/step_delegation.md diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index f1469253..9026396c 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -2,6 +2,8 @@ name: deepwork_jobs.define description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." user-invocable: false +context: fork +agent: deepwork-jobs --- @@ -22,462 +24,119 @@ user-invocable: false ## 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. +Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. ## Task Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. - -The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). +The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. ### Step 1: Understand the Job Purpose -Start by asking structured questions to understand what the user wants to accomplish: +Ask structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? - 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 1.5: Detect Document-Oriented Workflows +### Step 2: Detect Document-Oriented Workflows -**Check for document-focused patterns** in the user's description: -- Keywords: "report", "summary", "document", "create", "monthly", "quarterly", "for stakeholders", "for leadership" -- Final deliverable is a specific document (e.g., "AWS spending report", "competitive analysis", "sprint summary") +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly" +- Final deliverable is a specific document type - Recurring documents with consistent structure -**If a document-oriented workflow is detected:** - -1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first to ensure consistent quality." +**If detected**, inform the user and ask if they want to: +- Create a doc spec for consistent document quality +- Use an existing doc spec from `.deepwork/doc_specs/` +- Skip doc spec and proceed with simple outputs -2. Ask structured questions to understand if they want to: - - Create a doc spec for this document - - Use an existing doc spec (if any exist in `.deepwork/doc_specs/`) - - Skip doc spec and proceed with simple outputs +See the expert's documentation on doc specs for the full schema and examples. -### Step 1.6: Define the Doc Spec (if needed) +### Step 3: Define Each Step -When creating a doc spec, gather the following information: +For each major phase, gather: -1. **Document Identity** - - What is the document called? (e.g., "Monthly AWS Spending Report") - - Brief description of its purpose - - Where should these documents be stored? (path patterns like `finance/aws-reports/*.md`) +1. **Step Purpose**: What does this step accomplish? +2. **Inputs**: User parameters or files from previous steps +3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) +4. **Dependencies**: Which previous steps must complete first? +5. **Quality Criteria**: What makes a good vs. bad output? +6. **Agent Delegation**: Should this step run in a forked context? -2. **Audience and Context** - - Who reads this document? (target audience) - - How often is it produced? (frequency) +#### Work Product Storage Guidelines -3. **Quality Criteria** (3-5 criteria, each with name and description) - - **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve. +Job outputs belong in the main repository directory structure, not in dot-directories. - Examples for a spending report: - - **Visualization**: Must include charts showing spend breakdown by service - - **Variance Analysis**: Must compare current month against previous with percentages - - **Action Items**: Must include recommended cost optimization actions - - **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible. - -4. **Document Structure** - - What sections should it have? - - Any required elements (tables, charts, summaries)? - -### Step 1.7: Create the doc spec File (if needed) - -Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`: - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure. - -**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files). - -After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output. - -### Step 2: Define Each Step - -For each major phase they mentioned, ask structured questions to gather details: - -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? - - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output - - #### Work Product Storage Guidelines - - **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only. - - **Why this matters**: - - **Version control**: Work products in the main repo are tracked by git and visible in PRs - - **Discoverability**: Team members can find outputs without knowing about DeepWork internals - - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths - - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`) - - **Good output path patterns**: - ``` - competitive_research/competitors_list.md - competitive_research/acme_corp/research.md - operations/reports/2026-01/spending_analysis.md - docs/api/endpoints.md - ``` - - **Avoid these patterns**: - ``` - .deepwork/outputs/report.md # Hidden in dot-directory - output.md # Too generic, no context - research.md # Unclear which research - temp/draft.md # Transient-sounding paths - ``` - - **Organizing multi-file outputs**: - - Use the job name as a top-level folder when outputs are job-specific - - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/` - - Match existing project conventions when extending a codebase - - **When to include dates in paths**: - - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful. - ``` - operations/reports/2026-01/spending_analysis.md # Monthly report - keep history - hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf # Per-employee quarterly review - ``` - - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files. - ``` - competitive_research/acme_corp/swot.md # Current SWOT - updated over time - docs/architecture/overview.md # Living document - ``` - - **Supporting materials and intermediate outputs**: - - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output - - Name the dataroom folder by replacing the file extension with `_dataroom` - ``` - operations/reports/2026-01/spending_analysis.md # Final output - operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials - raw_data.csv - vendor_breakdown.md - notes.md - ``` - - This keeps supporting materials organized and discoverable without cluttering the main output location - -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? - -6. **Agent Delegation** (optional) - - Should this step be executed by a specific agent type? - - Use the `agent` field when the step should run in a forked context with a specific agent - - When `agent` is set, the generated skill automatically includes `context: fork` - - Available agent types: - - `general-purpose` - Standard agent for multi-step tasks - - ```yaml - steps: - - id: research_step - agent: general-purpose # Delegates to the general-purpose agent - ``` - -**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. - -#### Doc Spec-Aware Output Format - -When a step produces a document with a doc spec reference, use this format in job.yml: - -```yaml -outputs: - - file: reports/monthly_spending.md - doc_spec: .deepwork/doc_specs/monthly_aws_report.md +**Good patterns**: ``` - -The doc spec's quality criteria will automatically be included in the generated skill, ensuring consistent document quality. - -### Capability Considerations - -When defining steps, identify any that require specialized tools: - -**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. - -### Step 3: Validate the Workflow - -After gathering information about all steps: - -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: Define Quality Validation (Stop Hooks) - -For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. - -**Ask structured questions about quality validation:** -- "Are there specific quality criteria that must be met for this step?" -- "Would you like the agent to validate its work before completing?" -- "What would make you send the work back for revision?" - -**Stop hooks are particularly valuable for:** -- Steps with complex outputs that need multiple checks -- Steps where quality is critical (final deliverables) -- Steps with subjective quality criteria that benefit from AI self-review - -**Three types of stop hooks are supported:** - -1. **Inline Prompt** (`prompt`) - Best for simple quality criteria - ```yaml - stop_hooks: - - prompt: | - Verify the output meets these criteria: - 1. Contains at least 5 competitors - 2. Each competitor has a description - 3. Selection rationale is clear - ``` - -2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - -3. **Script** (`script`) - For programmatic validation (tests, linting) - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -**Multiple hooks can be combined:** -```yaml -stop_hooks: - - script: hooks/lint_output.sh - - prompt: "Verify the content is comprehensive and well-organized" +competitive_research/competitors_list.md +operations/reports/2026-01/spending_analysis.md ``` -**Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). - -### Step 5: Create the Job Directory and Specification - -Only after you have complete understanding, create the job directory and `job.yml` file: - -**First, create the directory structure** using the `make_new_job.sh` script: - -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +**Avoid**: ``` - -This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory -- `.deepwork/jobs/[job_name]/steps/` - For step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts -- `.deepwork/jobs/[job_name]/templates/` - For example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance - -**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) - -**Doc Spec**: See `.deepwork/doc_specs/job_spec.md` for the complete specification with quality criteria. - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. - -**Important**: -- Use lowercase with underscores for job name and step IDs -- Ensure file inputs reference steps in dependencies -- 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 -- Include a `changelog` section with an initial entry for version 1.0.0 - -## Example Dialog - +.deepwork/outputs/report.md # Hidden in dot-directory +output.md # Too generic ``` -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? +**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. -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 in the project root, or in a subdirectory like `research/` or `data/`? - -User: Just call it `competitors_list.md` in the project root. - -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! +**Supporting materials**: Place in `_dataroom` folder as peer to final output: +``` +operations/reports/2026-01/spending_analysis.md +operations/reports/2026-01/spending_analysis_dataroom/ + raw_data.csv + notes.md +``` -Claude: Great! Creating the job.yml specification now... +### Step 4: Validate the Workflow -[Creates .deepwork/jobs/competitive_research/job.yml with the complete spec] +After gathering all information: -✓ Job specification created! +1. **Review the flow** - Summarize and show how outputs feed into the next step +2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies +3. **Confirm details** - Job name, summary (max 200 chars), description, version -**File created:** -- .deepwork/jobs/competitive_research/job.yml +### Step 5: Create the Job Specification -**Next step:** -Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria. +**First, create the directory structure**: +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` -## Important Guidelines - -1. **Focus on specification only** - Don't create instruction files yet -2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool -3. **Rich context in description** - This helps with future refinement -4. **Validate understanding** - Summarize and confirm before creating -5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed +**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` -## 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 +Refer to the expert for the complete job.yml schema. Key validation rules: +- Job name: lowercase, underscores only, no spaces +- Version: semantic versioning (start with 1.0.0) +- Summary: max 200 characters - 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 +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example -The complete YAML specification file (example shown in Step 5 above). +## Output -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the new job being created) +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. After creating the file: 1. Inform the user that the specification is complete -2. Recommend that they review the job.yml file +2. Recommend they review the job.yml file 3. Tell them to run `/deepwork_jobs.review_job_spec` next - ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index a0c1d388..03ff85d7 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -2,6 +2,8 @@ name: deepwork_jobs.implement description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." user-invocable: false +context: fork +agent: deepwork-jobs --- @@ -26,235 +28,108 @@ Before proceeding, confirm these steps are complete: ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. +Read the `job.yml` specification and create all necessary files to make the job functional. -### Step 1: Create Directory Structure Using Script - -Run the `make_new_job.sh` script to create the standard directory structure: +### Step 1: Create Directory Structure +Run the setup script: ```bash .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory - `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) -- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: -```bash -mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates -touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep -``` +**Note**: If directory already exists from define step, create missing subdirectories manually. ### Step 2: Read and Validate the Specification -1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec 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 +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate structure (name, version, summary, description, steps) +3. Check dependencies are valid and non-circular +4. Extract step details for instruction generation ### 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`. +Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. +**Guidelines**: -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- `job.yml.example` - Complete job specification example -- `step_instruction.md.example` - Complete step instruction example - -**Guidelines for generating instructions:** - -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 +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to each 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 -6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks -7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" - -### Handling Stop Hooks - -If a step in the job.yml has `stop_hooks` defined, the generated instruction file should: - -1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the stop hooks will validate -2. **Be explicit about success** - Help the agent understand when the step is truly complete -3. **Include the promise pattern** - Mention that `✓ Quality Criteria Met` should be included when criteria are met - -**Example: If the job.yml has:** -```yaml -- id: research_competitors - name: "Research Competitors" - stop_hooks: - - prompt: | - Verify the research meets criteria: - 1. Each competitor has at least 3 data points - 2. Sources are cited - 3. Information is current (within last year) -``` - -**The instruction file should include:** -```markdown -## Quality Criteria +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - When a step has user inputs, MUST use this phrase +6. **Align with hooks** - If step has `hooks` defined, match quality criteria -- Each competitor has at least 3 distinct data points -- All information is sourced with citations -- Data is current (from within the last year) -- When all criteria are met, include `✓ Quality Criteria Met` in your response -``` - -This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. - -### Using Supplementary Reference Files +**Handling Hooks**: -Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. - -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. +If a step has hooks defined, the instruction file should: +- Mirror the quality criteria that hooks will validate +- Be explicit about what success looks like +- Mention the `Quality Criteria Met` pattern when criteria are met ### Step 4: Verify job.yml Location -Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it. +Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. ### Step 5: Sync Skills -Run `deepwork sync` to generate the skills for this job: - +Run: ```bash deepwork sync ``` -This will: -- Parse the job definition -- Generate skills for each step -- Make the skills available in `.claude/skills/` (or appropriate platform directory) +This generates skills for each step in `.claude/skills/` (or platform-specific directory). -### Step 6: Consider Rules for the New Job +### Step 6: Consider Rules -After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain. +After implementing, consider whether **rules** would help enforce quality. **What are rules?** +Automated guardrails in `.deepwork/rules/` that trigger when files change. -Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure: -- Documentation stays in sync with code -- Team guidelines are followed -- Architectural decisions are respected -- Quality standards are maintained - -**When to suggest rules:** - -Think about the job you just implemented and ask: -- Does this job produce outputs that other files depend on? -- Are there documentation files that should be updated when this job's outputs change? -- Are there quality checks or reviews that should happen when certain files in this domain change? -- Could changes to the job's output files impact other parts of the project? - -**Examples of rules that might make sense:** +**When to suggest rules**: +- Job produces outputs that other files depend on +- Documentation should stay in sync with outputs +- Quality checks should happen when certain files change +**Examples**: | Job Type | Potential Rule | |----------|----------------| -| API Design | "Update API docs when endpoint definitions change" | -| Database Schema | "Review migrations when schema files change" | -| Competitive Research | "Update strategy docs when competitor analysis changes" | -| Feature Development | "Update changelog when feature files change" | -| Configuration Management | "Update install guide when config files change" | - -**How to offer rule creation:** +| API Design | Update docs when endpoints change | +| Database Schema | Review migrations when schema changes | +| Competitive Research | Update strategy when analysis changes | -If you identify one or more rules that would benefit the user, explain: -1. **What the rule would do** - What triggers it and what action it prompts -2. **Why it would help** - How it prevents common mistakes or keeps things in sync -3. **What files it would watch** - The trigger patterns - -Then ask the user: - -> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up." - -If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule. - -**Example dialogue:** - -``` -Based on the competitive_research job you just created, I noticed that when -competitor analysis files change, it would be helpful to remind you to update -your strategy documentation. - -I'd suggest a rule like: -- **Name**: "Update strategy when competitor analysis changes" -- **Trigger**: `**/positioning_report.md` -- **Action**: Prompt to review and update `docs/strategy.md` - -Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up. -``` - -**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense. - -## Example Implementation - -For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - -## Important Guidelines - -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) -- No file system errors +If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. ## 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 +Before marking complete: +- [ ] job.yml validated and in place +- [ ] All step instruction files created (complete, not stubs) +- [ ] Instructions are specific and actionable +- [ ] Output examples provided +- [ ] Quality criteria defined for each step +- [ ] User input steps use "ask structured questions" - [ ] `deepwork sync` executed successfully -- [ ] Skills generated in platform directory -- [ ] Considered whether rules would benefit this job (Step 6) -- [ ] If rules suggested, offered to run `/deepwork_rules.define` - -## 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 -- Steps with user inputs explicitly use "ask structured questions" phrasing -- Sync completed successfully -- Skills available for use -- Thoughtfully considered relevant rules for the job domain +- [ ] Skills available in platform directory +- [ ] Considered relevant rules for job domain + +## Output + +Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. ### Job Context diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index 95e1c61f..83de5777 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -1,6 +1,8 @@ --- name: deepwork_jobs.learn description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." +context: fork +agent: deepwork-jobs --- @@ -19,357 +21,140 @@ description: "Analyzes conversation history to improve job instructions and capt ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. ## Task -Analyze the conversation history to extract learnings and improvements, then apply them appropriately: -- **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic +Analyze the conversation history to extract learnings and apply them appropriately: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md ### Step 1: Analyze Conversation for Job Executions -1. **Scan the conversation** for DeepWork slash commands that were run - - Look for patterns like `/job_name.step_id` - - Identify which jobs and steps were executed - - Note the order of execution +1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns +2. **Identify the target folder** - Deepest common folder for future work on this topic +3. **If no job specified**, ask the user which job to analyze -2. **Identify the target folder** - - This should be the deepest common folder that would contain all work on the topic in the future - - Should be clear from conversation history where work was done - - If unclear, run `git diff` to see where changes were made on the branch - -3. **If no job was specified**, ask the user: - - "Which DeepWork job would you like me to learn from?" - - List available jobs from `.deepwork/jobs/` - -### Step 2: Identify Points of Confusion and Inefficiency +### Step 2: Identify Issues Review the conversation for: -1. **Confusion signals** - - Questions the agent asked that shouldn't have been necessary - - Misunderstandings about what a step required - - Incorrect outputs that needed correction - - Ambiguous instructions that led to wrong interpretations +**Confusion signals**: +- Unnecessary questions from the agent +- Misunderstandings about step requirements +- Incorrect outputs needing correction -2. **Inefficiency signals** - - Extra steps or iterations that were needed - - Information that had to be repeated - - Context that was missing from instructions - - Dependencies that weren't clear +**Inefficiency signals**: +- Extra iterations needed +- Information repeated multiple times +- Missing context or dependencies -3. **Error patterns** - - Failed validations and why they failed - - Quality criteria that were misunderstood - - Edge cases that weren't handled +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -4. **Success patterns** - - What worked particularly well - - Efficient approaches worth preserving - - Good examples that could be added to instructions +**Success patterns**: +- What worked well +- Efficient approaches to preserve ### Step 3: Classify Learnings -For each learning identified, determine if it is: - -**Generalizable** (should improve instructions): +**Generalizable** (update instructions): - Would help ANY future run of this job - Addresses unclear or missing guidance -- Fixes incorrect assumptions in instructions -- Adds helpful examples or context -- Examples: - - "Step instructions should mention that X format is required" - - "Quality criteria should include checking for Y" - - "Add example of correct output format" - -**doc spec-Related** (should improve doc spec files): +- Adds helpful examples + +**Doc spec-related** (update doc spec files): - Improvements to document quality criteria -- Changes to document structure or format -- Updated audience or frequency information -- Examples: - - "The report should include a summary table" - - "Quality criterion 'Visualization' needs clearer requirements" - - "Documents need a section for action items" - -**Bespoke** (should go in AGENTS.md): +- Changes to document structure +- Updated audience or format info + +**Bespoke** (add to AGENTS.md): - Specific to THIS project/codebase/run -- Depends on local conventions or structure - References specific files or paths -- Would not apply to other uses of this job -- Examples: - - "In this codebase, API endpoints are in `src/api/`" - - "This project uses camelCase for function names" - - "The main config file is at `config/settings.yml`" - -### Step 3.5: Identify doc spec-Related Learnings - -Review the conversation for doc spec-related improvements: - -1. **Quality Criteria Changes** - - Were any quality criteria unclear or insufficient? - - Did the agent repeatedly fail certain criteria? - - Are there new criteria that should be added? - -2. **Document Structure Changes** - - Did the user request different sections? - - Were parts of the document format confusing? - - Should the example document be updated? - -3. **Metadata Updates** - - Has the target audience changed? - - Should frequency or path patterns be updated? - -**Signals for doc spec improvements:** -- User asked for changes to document format -- Repeated validation failures on specific criteria -- Feedback about missing sections or information -- Changes to how documents are organized/stored - -### Step 4: Update Job Instructions (Generalizable Learnings) - -For each generalizable learning: - -1. **Locate the instruction file** - - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements** - - Add missing context or clarification - - Include helpful examples - - Clarify ambiguous instructions - - Update quality criteria if needed - -3. **Keep instructions concise** - - Avoid redundancy - don't repeat the same guidance in multiple places - - Be direct - remove verbose explanations that don't add value - - Prefer bullet points over paragraphs where appropriate - -4. **Preserve instruction structure** - - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - - Add to appropriate sections rather than restructuring - - Maintain consistency with other steps - -5. **Track changes for changelog** - - Note what was changed and why - - Prepare changelog entry for job.yml +- Local conventions -### Step 4b: Extract Shared Content into Referenced Files +### Step 4: Update Job Instructions -Review all instruction files for the job and identify content that: -- Appears in multiple step instructions (duplicated) -- Is lengthy and could be extracted for clarity -- Would benefit from being maintained in one place +For generalizable learnings: -**Extract to shared files:** +1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements - add context, examples, clarify ambiguity +3. Keep instructions concise - no redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) +5. Note changes for changelog -1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` - - `conventions.md` - Coding/formatting conventions used across steps - - `examples.md` - Common examples referenced by multiple steps - - `schemas.md` - Data structures or formats used throughout +**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. -2. **Reference from instructions** using markdown includes or explicit references: - ```markdown - ## Conventions +### Step 5: Update Doc Spec Files (If Applicable) - Follow the conventions defined in `shared/conventions.md`. - ``` - -3. **Benefits of extraction:** - - Single source of truth - update once, applies everywhere - - Shorter instruction files - easier to read and maintain - - Consistent guidance across steps - -### Step 4.5: Update doc spec Files (doc spec-Related Learnings) - -If doc spec-related learnings were identified: - -1. **Locate the doc spec file** - - Find doc spec references in job.yml outputs (look for `doc_spec: .deepwork/doc_specs/[doc_spec_name].md`) - - doc spec files are at `.deepwork/doc_specs/[doc_spec_name].md` +If doc spec learnings were identified: -2. **Update quality_criteria array** - - Add new criteria with name and description - - Modify existing criteria descriptions for clarity - - Remove criteria that are no longer relevant +1. Find doc spec references in job.yml outputs +2. Update quality criteria with clearer requirements +3. Update example document if structure changed +4. Update metadata (audience, frequency, paths) -3. **Update example document** - - Modify the markdown body to reflect structure changes - - Ensure the example matches updated criteria +### Step 6: Create/Update AGENTS.md -4. **Update metadata as needed** - - target_audience: If audience has changed - - frequency: If production cadence has changed - - path_patterns: If storage location has changed +For bespoke learnings: -**Example doc spec update:** -```yaml -# Before -quality_criteria: - - name: Visualization - description: Include charts +1. **Determine location** - Deepest common folder for the topic +2. **Use file references** - Link to source files rather than duplicating content +3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` -# After -quality_criteria: - - name: Visualization - description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend +**Good patterns** (references): +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` ``` -### Step 5: Create/Update AGENTS.md (Bespoke Learnings) - -The AGENTS.md file captures project-specific knowledge that helps future agent runs. - -1. **Determine the correct location** - - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - - This ensures the knowledge is available when working in that context - - If uncertain, place at the project root - -2. **Use file references where possible** - - Instead of duplicating information, reference source files - - This keeps AGENTS.md in sync as the codebase evolves - - Pattern: "See `path/to/file.ext` for [description]" - -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. - -4. **Writing entries** - - Be concise but specific - - Always prefer file references over inline content - - Use line numbers when referencing specific code: `file.ext:42` - - Group related learnings together +**Avoid** (duplicating): +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +``` -### Step 6: Update Job Version and Changelog +### Step 7: Update Job Version and Changelog If instruction files were modified: -1. **Bump version in job.yml** - - Patch version (0.0.x) for instruction improvements - - Minor version (0.x.0) if quality criteria changed - -2. **Add changelog entry** +1. Bump version (patch for improvements, minor for criteria changes) +2. Add changelog entry: ```yaml - version: "[new_version]" - changes: "Improved [step] instructions based on execution learnings: [brief description]" + changes: "Improved [step] based on execution learnings: [brief description]" ``` -### Step 7: Sync Skills +### Step 8: Sync Skills -**Run deepwork sync** (if instructions were modified) +If instructions were modified: ```bash deepwork sync ``` -## File Reference Patterns - -When adding entries to AGENTS.md, prefer these patterns: - -**Good (references)**: -```markdown -- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` -- Configuration schema: Defined in `config/schema.json` -``` - -**Avoid (duplicating)**: -```markdown -- API endpoints should return JSON with this format: { status: ..., data: ... } -- Error handling should use try/catch with custom error classes -- Configuration requires these fields: name, version, ... -``` - ## Quality Criteria -- Conversation has been analyzed for job executions -- Points of confusion and inefficiency are identified -- Learnings are correctly classified (generalizable vs bespoke) -- Job instructions updated for generalizable improvements -- Instructions are concise - no redundancy or unnecessary verbosity -- Shared/lengthy content extracted into referenced files where appropriate -- AGENTS.md created/updated with bespoke learnings -- File references used instead of duplicating content -- AGENTS.md is in the correct folder (the deepest common folder for the topic) -- When all criteria are met, include `✓ Quality Criteria Met` - -## Example Dialog - -``` -User: /deepwork_jobs.learn - -Claude: I'll analyze this conversation for learnings from DeepWork job executions. - -**Conversation Analysis** - -I found the following job executions: -1. `/competitive_research.identify_competitors` - Completed -2. `/competitive_research.research_competitors` - Completed with 2 iterations -3. `/competitive_research.comparative_analysis` - Completed - -**Identified Issues** - -1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. - -2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. - -**Classification** - -- Generalizable: Add pricing to research requirements in instructions -- Bespoke: This project focuses on B2B SaaS in the HR tech space - -**Actions Taken** - -1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: - - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements - - Added note about carrying forward industry context from previous step - -2. Created `./competitive_research_output/AGENTS.md`: - ```markdown - # Project Context for Competitive Research - - ## Job-Specific Context - - ### competitive_research - - #### Industry Focus - - Domain: B2B SaaS, HR Technology sector - - See `identify_competitors_output.md` for market definition - - #### Competitors Identified - - Reference: `competitor_list.md` for full details - - ## Last Updated - - Date: 2024-01-15 - - From conversation about: Initial competitive analysis run - ``` - -3. Updated job.yml version to 1.0.1 with changelog entry - -4. Ran `deepwork sync` - -**Summary** - -Updated job instructions and created AGENTS.md with bespoke learnings. -``` +- Conversation analyzed for job executions +- Learnings correctly classified (generalizable vs bespoke) +- Instructions updated for generalizable improvements +- Instructions remain concise +- Shared content extracted where appropriate +- AGENTS.md in correct folder with file references +- Sync complete if instructions modified +- When complete: `Quality Criteria Met` -## Handling Edge Cases +## Edge Cases -**No job executions found**: -- Ask user which job they'd like to analyze -- Or offer to review available jobs +**No job executions found**: Ask user which job to analyze -**Multiple jobs executed**: -- Analyze each job separately -- Create separate AGENTS.md entries or files as appropriate +**Multiple jobs executed**: Analyze each separately -**AGENTS.md already exists**: -- Read existing content -- Append new learnings to appropriate sections -- Update "Last Updated" section +**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" -**No issues found**: -- Document what worked well -- Consider if any successful patterns should be added to instructions as examples +**No issues found**: Document what worked well, consider adding as examples -**Sensitive information**: -- Never include secrets, credentials, or PII in AGENTS.md -- Reference config files instead of including values +**Sensitive information**: Never include secrets or PII - reference config files instead ### Job Context diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 51b8ed54..6815da8c 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -2,6 +2,8 @@ name: deepwork_jobs.review_job_spec description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." user-invocable: false +context: fork +agent: deepwork-jobs --- @@ -26,210 +28,108 @@ Before proceeding, confirm these steps are complete: ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass. +Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. ### Step 1: Read the Job Specification -Read the `job.yml` file created in the define step: - -``` -.deepwork/jobs/[job_name]/job.yml -``` - -Also read the doc spec for reference: - -``` -.deepwork/doc_specs/job_spec.md -``` +Read both files: +- `.deepwork/jobs/[job_name]/job.yml` - The specification to review +- `.deepwork/doc_specs/job_spec.md` - The quality criteria ### Step 2: Spawn Review Sub-Agent -Use the Task tool to spawn a sub-agent that will provide an unbiased review: +Use the Task tool with: +- `subagent_type`: "general-purpose" +- `model`: "haiku" +- `description`: "Review job.yml against doc spec" -``` -Task tool parameters: -- subagent_type: "general-purpose" -- model: "haiku" -- description: "Review job.yml against doc spec" -- prompt: [see below] -``` - -**Sub-agent prompt template:** +**Sub-agent prompt**: ``` -Review this job.yml against the following 9 quality criteria from the doc spec. +Review this job.yml against the following 9 quality criteria. -For each criterion, respond with: -- PASS or FAIL -- If FAIL: specific issue and suggested fix +For each criterion, respond with PASS or FAIL. +If FAIL: provide the specific issue and suggested fix. ## job.yml Content -[paste the full job.yml content here] +[paste full job.yml content] ## Quality Criteria -1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`) - -2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`) - -3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes - -4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users - -5. **Changelog Present**: Must include a changelog array with at least the initial version entry - -6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array - -7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references - -8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array - -9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`) +1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) +2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) +3. **Concise Summary**: Under 200 characters, describes what job accomplishes +4. **Rich Description**: Multi-line explaining problem, process, outcomes, users +5. **Changelog Present**: Array with at least initial version entry +6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: Reference existing step IDs, no circular references +8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies +9. **Output Paths**: Valid filenames or paths ## Response Format -Respond with a structured evaluation: - ### Overall: [X/9 PASS] ### Criterion Results - 1. Valid Identifier: [PASS/FAIL] [If FAIL: Issue and fix] - -2. Semantic Version: [PASS/FAIL] - [If FAIL: Issue and fix] - -[... continue for all 9 criteria ...] +... ### Summary of Required Fixes - -[List any fixes needed, or "No fixes required - all criteria pass"] +[List fixes needed, or "No fixes required"] ``` -### Step 3: Review Sub-Agent Findings +### Step 3: Review Findings Parse the sub-agent's response: - -1. **Count passing criteria** - How many of the 9 criteria passed? -2. **Identify failures** - List specific criteria that failed -3. **Note suggested fixes** - What changes does the sub-agent recommend? +1. Count passing criteria +2. Identify failures +3. Note suggested fixes ### Step 4: Fix Failed Criteria -For each failed criterion, edit the job.yml to address the issue: +Edit job.yml to address each failure: -**Common fixes by criterion:** - -| Criterion | Common Issue | Fix | -|-----------|-------------|-----| -| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | -| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format | -| Concise Summary | Too long or vague | Shorten to <200 chars, be specific | -| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users | -| Changelog Present | Missing changelog | Add `changelog:` with initial version entry | -| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies | -| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies | -| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array | -| Output Paths | Invalid characters or format | Use valid filename/path format | +| Criterion | Common Fix | +|-----------|-----------| +| Valid Identifier | Convert to lowercase_underscores | +| Semantic Version | Set to `"1.0.0"` or fix format | +| Concise Summary | Shorten to <200 chars | +| Rich Description | Add multi-line explanation | +| Changelog Present | Add `changelog:` array | +| Complete Steps | Add missing required fields | +| Valid Dependencies | Fix step ID reference | +| Input Consistency | Add referenced step to dependencies | +| Output Paths | Use valid filename/path format | ### Step 5: Re-Run Review (If Needed) If any criteria failed: - -1. **Spawn a new sub-agent** with the updated job.yml content -2. **Review the new findings** -3. **Fix any remaining issues** -4. **Repeat until all 9 criteria pass** +1. Spawn a new sub-agent with updated job.yml +2. Review new findings +3. Fix remaining issues +4. Repeat until all 9 criteria pass ### Step 6: Confirm Completion When all 9 criteria pass: -1. **Announce success**: "All 9 doc spec quality criteria pass." -2. **List what was validated**: - - Valid Identifier - - Semantic Version - - Concise Summary - - Rich Description - - Changelog Present - - Complete Steps - - Valid Dependencies - - Input Consistency - - Output Paths -3. **Include the promise**: `Quality Criteria Met` -4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files." - -## Example Review Cycle - -``` -Claude: Let me review the job.yml against the doc spec quality criteria. - -[Spawns sub-agent with haiku model] - -Sub-agent response: -### Overall: 7/9 PASS - -### Criterion Results -1. Valid Identifier: PASS -2. Semantic Version: PASS -3. Concise Summary: FAIL - Issue: Summary is 245 characters, exceeds 200 char limit - Fix: Shorten to "Competitive analysis workflow for product positioning" -4. Rich Description: PASS -5. Changelog Present: FAIL - Issue: No changelog array present - Fix: Add changelog with initial version entry -6. Complete Steps: PASS -7. Valid Dependencies: PASS -8. Input Consistency: PASS -9. Output Paths: PASS - -### Summary of Required Fixes -1. Shorten summary to under 200 characters -2. Add changelog array with initial version - -Claude: I found 2 issues. Let me fix them. - -[Edits job.yml to shorten summary and add changelog] - -Claude: Let me verify the fixes with another review. - -[Spawns new sub-agent] - -Sub-agent response: -### Overall: 9/9 PASS - -### Summary of Required Fixes -No fixes required - all criteria pass - -Claude: All 9 doc spec quality criteria pass. - -Quality Criteria Met - -**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files. -``` - -## Quality Criteria - -- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review) -- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec -- **Findings Addressed**: All failed criteria were fixed by the main agent -- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed -- **Promise Included**: The response includes `Quality Criteria Met` when complete +1. Announce: "All 9 doc spec quality criteria pass." +2. Include: `Quality Criteria Met` +3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. ### Job Context diff --git a/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md b/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md index 657e486e..ecbd239f 100644 --- a/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md +++ b/.deepwork/experts/deepwork_jobs/topics/job_yml_schema.md @@ -86,12 +86,39 @@ steps: quality_criteria: - "All competitors have descriptions" - "Sources are cited" - agent: general-purpose # delegate to agent type + agent: deepwork-jobs # delegate to expert (see Agent Delegation) hooks: after_agent: - script: hooks/validate.sh ``` +### Agent Delegation (The `agent` Field) + +The `agent` field specifies which expert should execute this step. When set: +1. The generated skill includes `context: fork` (runs in isolated context) +2. The generated skill includes `agent: [expert-name]` (loads that expert's knowledge) +3. The step runs with all the expert's topics, learnings, and domain knowledge available + +**This is how you make a step "run via" an expert.** + +```yaml +steps: + - id: define + name: "Define Job Specification" + description: "Creates a job.yml specification..." + instructions_file: steps/define.md + agent: deepwork-jobs # Runs with deepwork-jobs expert loaded + outputs: + - job.yml +``` + +Common agent values: +- `deepwork-jobs` - Expert for DeepWork job creation and management +- `deepwork-rules` - Expert for DeepWork rule creation +- Custom experts you've defined in `.deepwork/experts/` + +See the **Step Delegation** topic for detailed examples and patterns. + ## Output Formats Simple string: diff --git a/.deepwork/experts/deepwork_jobs/topics/step_delegation.md b/.deepwork/experts/deepwork_jobs/topics/step_delegation.md new file mode 100644 index 00000000..0efad748 --- /dev/null +++ b/.deepwork/experts/deepwork_jobs/topics/step_delegation.md @@ -0,0 +1,145 @@ +--- +name: Step Delegation to Experts +keywords: + - agent + - expert + - delegation + - context fork + - sub-agent +last_updated: 2025-02-01 +--- + +# Step Delegation to Experts + +How to make job steps run via experts using the `agent` field. + +## The `agent` Field + +The `agent` field in a step definition specifies which expert should execute that step. This is the primary mechanism for making steps "run via" an expert. + +```yaml +steps: + - id: define + name: "Define Job Specification" + description: "Creates a job.yml specification..." + instructions_file: steps/define.md + agent: deepwork-jobs # <-- This step runs via the deepwork-jobs expert + outputs: + - job.yml +``` + +## What Happens When You Set `agent` + +When a step has `agent: expert-name`, the generated skill includes: + +1. **`context: fork`** - The step runs in an isolated context (sub-agent) +2. **`agent: expert-name`** - The expert's knowledge is loaded into that context + +The resulting skill frontmatter looks like: + +```yaml +--- +name: my_job.define +description: "Creates a job.yml specification..." +context: fork +agent: deepwork-jobs +--- +``` + +## How Expert Knowledge Flows + +When the skill runs: + +1. A forked context (sub-agent) is created +2. The expert file (e.g., `.claude/agents/dwe_deepwork-jobs.md`) is loaded +3. All expert topics, learnings, and domain knowledge become available +4. The step instructions execute with this enhanced context +5. The sub-agent completes and returns to the parent context + +## Real-World Example: deepwork_jobs + +The `deepwork_jobs` job itself uses expert delegation. All steps run via the `deepwork-jobs` expert: + +```yaml +steps: + - id: define + name: "Define Job Specification" + description: "Creates a job.yml specification..." + instructions_file: steps/define.md + agent: deepwork-jobs # Runs with job schema knowledge + outputs: + - file: job.yml + doc_spec: .deepwork/doc_specs/job_spec.md + + - id: review_job_spec + name: "Review Job Specification" + description: "Reviews job.yml against quality criteria..." + instructions_file: steps/review_job_spec.md + agent: deepwork-jobs # Same expert, different step + inputs: + - file: job.yml + from_step: define + outputs: + - file: job.yml + doc_spec: .deepwork/doc_specs/job_spec.md + + - id: implement + name: "Implement Job Steps" + description: "Generates step instruction files..." + instructions_file: steps/implement.md + agent: deepwork-jobs # Expert knowledge helps write good instructions + inputs: + - file: job.yml + from_step: review_job_spec + outputs: + - steps/ +``` + +## When to Use Expert Delegation + +Use `agent: expert-name` when: + +1. **Domain expertise is needed** - The step requires specialized knowledge that an expert provides +2. **Consistency across steps** - Multiple steps in a job should use the same expert context +3. **Complex validation** - The expert has knowledge about quality criteria or best practices +4. **Template awareness** - The expert knows about file formats, schemas, or conventions + +## Available Experts + +Standard experts that ship with DeepWork: + +- `deepwork-jobs` - Expert on job.yml schema, step instructions, skill generation +- `deepwork-rules` - Expert on rule creation and file-change triggers + +Custom experts can be created in `.deepwork/experts/` and referenced by name. + +## Expert vs. Sub-Agent Quality Review + +Note the difference between: + +1. **Expert delegation** (`agent: deepwork-jobs`) - The entire step runs with expert knowledge loaded +2. **Sub-agent quality review** (`quality_criteria` field) - A Haiku sub-agent validates outputs against criteria + +These can be combined - a step can run via an expert AND have quality criteria validated by a sub-agent: + +```yaml +steps: + - id: implement + instructions_file: steps/implement.md + agent: deepwork-jobs # Expert knowledge during execution + quality_criteria: # Sub-agent validates outputs + - "All instruction files are complete" + - "No placeholder content remains" +``` + +## Troubleshooting + +**Step not using expert knowledge?** +- Verify `agent: expert-name` is set in job.yml +- Run `deepwork sync` to regenerate skills +- Check the generated skill has `agent:` in its frontmatter + +**Expert not found?** +- Ensure the expert exists in `.deepwork/experts/[expert-name]/` +- Run `deepwork sync` to generate the expert agent file +- Check `.claude/agents/dwe_[expert-name].md` exists diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 4343cbda..3b14c068 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "1.0.0" +version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -22,32 +22,35 @@ workflows: - implement changelog: + - version: "1.1.0" + changes: "Simplified step instructions to leverage deepwork-jobs expert; cleaned up redundant content; improved clarity and conciseness" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - - version: "0.1.0" - changes: "Initial version" - - version: "0.2.0" - changes: "Replaced refine command with learn command for conversation-driven improvement" - - version: "0.3.0" - changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples" - - version: "0.4.0" - changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" - - version: "0.5.0" - changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions" - - version: "0.6.0" - changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation; learn.md now identifies and applies doc spec-related improvements" - - version: "0.7.0" - changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" - - version: "0.8.0" - changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" - version: "0.9.0" changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" + - version: "0.8.0" + changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" + - version: "0.7.0" + changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" + - version: "0.6.0" + changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation" + - version: "0.5.0" + changes: "Standardized on 'ask structured questions' phrasing for user input" + - version: "0.4.0" + changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" + - version: "0.3.0" + changes: "Added make_new_job.sh script and templates directory" + - version: "0.2.0" + changes: "Replaced refine command with learn command for conversation-driven improvement" + - version: "0.1.0" + changes: "Initial version" steps: - id: define name: "Define Job Specification" description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." instructions_file: steps/define.md + agent: deepwork-jobs inputs: - name: job_purpose description: "What complex task or workflow are you trying to accomplish?" @@ -59,6 +62,7 @@ steps: name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." instructions_file: steps/review_job_spec.md + agent: deepwork-jobs inputs: - file: job.yml from_step: define @@ -77,6 +81,7 @@ steps: name: "Implement Job Steps" description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." instructions_file: steps/implement.md + agent: deepwork-jobs inputs: - file: job.yml from_step: review_job_spec @@ -99,6 +104,7 @@ steps: name: "Learn from Job Execution" description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." instructions_file: steps/learn.md + agent: deepwork-jobs exposed: true inputs: - name: job_name diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index 31de7440..237d2cd7 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -2,457 +2,114 @@ ## 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. +Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. ## Task Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. - -The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). +The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. ### Step 1: Understand the Job Purpose -Start by asking structured questions to understand what the user wants to accomplish: +Ask structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? - 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 1.5: Detect Document-Oriented Workflows +### Step 2: Detect Document-Oriented Workflows -**Check for document-focused patterns** in the user's description: -- Keywords: "report", "summary", "document", "create", "monthly", "quarterly", "for stakeholders", "for leadership" -- Final deliverable is a specific document (e.g., "AWS spending report", "competitive analysis", "sprint summary") +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly" +- Final deliverable is a specific document type - Recurring documents with consistent structure -**If a document-oriented workflow is detected:** - -1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first to ensure consistent quality." +**If detected**, inform the user and ask if they want to: +- Create a doc spec for consistent document quality +- Use an existing doc spec from `.deepwork/doc_specs/` +- Skip doc spec and proceed with simple outputs -2. Ask structured questions to understand if they want to: - - Create a doc spec for this document - - Use an existing doc spec (if any exist in `.deepwork/doc_specs/`) - - Skip doc spec and proceed with simple outputs +See the expert's documentation on doc specs for the full schema and examples. -### Step 1.6: Define the Doc Spec (if needed) +### Step 3: Define Each Step -When creating a doc spec, gather the following information: +For each major phase, gather: -1. **Document Identity** - - What is the document called? (e.g., "Monthly AWS Spending Report") - - Brief description of its purpose - - Where should these documents be stored? (path patterns like `finance/aws-reports/*.md`) +1. **Step Purpose**: What does this step accomplish? +2. **Inputs**: User parameters or files from previous steps +3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) +4. **Dependencies**: Which previous steps must complete first? +5. **Quality Criteria**: What makes a good vs. bad output? +6. **Agent Delegation**: Should this step run in a forked context? -2. **Audience and Context** - - Who reads this document? (target audience) - - How often is it produced? (frequency) +#### Work Product Storage Guidelines -3. **Quality Criteria** (3-5 criteria, each with name and description) - - **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve. +Job outputs belong in the main repository directory structure, not in dot-directories. - Examples for a spending report: - - **Visualization**: Must include charts showing spend breakdown by service - - **Variance Analysis**: Must compare current month against previous with percentages - - **Action Items**: Must include recommended cost optimization actions - - **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible. - -4. **Document Structure** - - What sections should it have? - - Any required elements (tables, charts, summaries)? - -### Step 1.7: Create the doc spec File (if needed) - -Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`: - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure. - -**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files). - -After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output. - -### Step 2: Define Each Step - -For each major phase they mentioned, ask structured questions to gather details: - -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? - - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output - - #### Work Product Storage Guidelines - - **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only. - - **Why this matters**: - - **Version control**: Work products in the main repo are tracked by git and visible in PRs - - **Discoverability**: Team members can find outputs without knowing about DeepWork internals - - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths - - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`) - - **Good output path patterns**: - ``` - competitive_research/competitors_list.md - competitive_research/acme_corp/research.md - operations/reports/2026-01/spending_analysis.md - docs/api/endpoints.md - ``` - - **Avoid these patterns**: - ``` - .deepwork/outputs/report.md # Hidden in dot-directory - output.md # Too generic, no context - research.md # Unclear which research - temp/draft.md # Transient-sounding paths - ``` - - **Organizing multi-file outputs**: - - Use the job name as a top-level folder when outputs are job-specific - - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/` - - Match existing project conventions when extending a codebase - - **When to include dates in paths**: - - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful. - ``` - operations/reports/2026-01/spending_analysis.md # Monthly report - keep history - hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf # Per-employee quarterly review - ``` - - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files. - ``` - competitive_research/acme_corp/swot.md # Current SWOT - updated over time - docs/architecture/overview.md # Living document - ``` - - **Supporting materials and intermediate outputs**: - - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output - - Name the dataroom folder by replacing the file extension with `_dataroom` - ``` - operations/reports/2026-01/spending_analysis.md # Final output - operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials - raw_data.csv - vendor_breakdown.md - notes.md - ``` - - This keeps supporting materials organized and discoverable without cluttering the main output location - -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? - -6. **Agent Delegation** (optional) - - Should this step be executed by a specific agent type? - - Use the `agent` field when the step should run in a forked context with a specific agent - - When `agent` is set, the generated skill automatically includes `context: fork` - - Available agent types: - - `general-purpose` - Standard agent for multi-step tasks - - ```yaml - steps: - - id: research_step - agent: general-purpose # Delegates to the general-purpose agent - ``` - -**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. - -#### Doc Spec-Aware Output Format - -When a step produces a document with a doc spec reference, use this format in job.yml: - -```yaml -outputs: - - file: reports/monthly_spending.md - doc_spec: .deepwork/doc_specs/monthly_aws_report.md +**Good patterns**: ``` - -The doc spec's quality criteria will automatically be included in the generated skill, ensuring consistent document quality. - -### Capability Considerations - -When defining steps, identify any that require specialized tools: - -**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. - -### Step 3: Validate the Workflow - -After gathering information about all steps: - -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: Define Quality Validation (Stop Hooks) - -For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. - -**Ask structured questions about quality validation:** -- "Are there specific quality criteria that must be met for this step?" -- "Would you like the agent to validate its work before completing?" -- "What would make you send the work back for revision?" - -**Stop hooks are particularly valuable for:** -- Steps with complex outputs that need multiple checks -- Steps where quality is critical (final deliverables) -- Steps with subjective quality criteria that benefit from AI self-review - -**Three types of stop hooks are supported:** - -1. **Inline Prompt** (`prompt`) - Best for simple quality criteria - ```yaml - stop_hooks: - - prompt: | - Verify the output meets these criteria: - 1. Contains at least 5 competitors - 2. Each competitor has a description - 3. Selection rationale is clear - ``` - -2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - -3. **Script** (`script`) - For programmatic validation (tests, linting) - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -**Multiple hooks can be combined:** -```yaml -stop_hooks: - - script: hooks/lint_output.sh - - prompt: "Verify the content is comprehensive and well-organized" +competitive_research/competitors_list.md +operations/reports/2026-01/spending_analysis.md ``` -**Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). - -### Step 5: Create the Job Directory and Specification - -Only after you have complete understanding, create the job directory and `job.yml` file: - -**First, create the directory structure** using the `make_new_job.sh` script: - -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +**Avoid**: ``` - -This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory -- `.deepwork/jobs/[job_name]/steps/` - For step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts -- `.deepwork/jobs/[job_name]/templates/` - For example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance - -**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) - -**Doc Spec**: See `.deepwork/doc_specs/job_spec.md` for the complete specification with quality criteria. - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. - -**Important**: -- Use lowercase with underscores for job name and step IDs -- Ensure file inputs reference steps in dependencies -- 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 -- Include a `changelog` section with an initial entry for version 1.0.0 - -## Example Dialog - +.deepwork/outputs/report.md # Hidden in dot-directory +output.md # Too generic ``` -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? +**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. -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 in the project root, or in a subdirectory like `research/` or `data/`? - -User: Just call it `competitors_list.md` in the project root. - -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! +**Supporting materials**: Place in `_dataroom` folder as peer to final output: +``` +operations/reports/2026-01/spending_analysis.md +operations/reports/2026-01/spending_analysis_dataroom/ + raw_data.csv + notes.md +``` -Claude: Great! Creating the job.yml specification now... +### Step 4: Validate the Workflow -[Creates .deepwork/jobs/competitive_research/job.yml with the complete spec] +After gathering all information: -✓ Job specification created! +1. **Review the flow** - Summarize and show how outputs feed into the next step +2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies +3. **Confirm details** - Job name, summary (max 200 chars), description, version -**File created:** -- .deepwork/jobs/competitive_research/job.yml +### Step 5: Create the Job Specification -**Next step:** -Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria. +**First, create the directory structure**: +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` -## Important Guidelines - -1. **Focus on specification only** - Don't create instruction files yet -2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool -3. **Rich context in description** - This helps with future refinement -4. **Validate understanding** - Summarize and confirm before creating -5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed +**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` -## 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 +Refer to the expert for the complete job.yml schema. Key validation rules: +- Job name: lowercase, underscores only, no spaces +- Version: semantic versioning (start with 1.0.0) +- Summary: max 200 characters - 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 +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example -The complete YAML specification file (example shown in Step 5 above). +## Output -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the new job being created) +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. After creating the file: 1. Inform the user that the specification is complete -2. Recommend that they review the job.yml file +2. Recommend they review the job.yml file 3. Tell them to run `/deepwork_jobs.review_job_spec` next - diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md index 749c8c6f..bc1fa3d8 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md @@ -2,232 +2,105 @@ ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. +Read the `job.yml` specification and create all necessary files to make the job functional. -### Step 1: Create Directory Structure Using Script - -Run the `make_new_job.sh` script to create the standard directory structure: +### Step 1: Create Directory Structure +Run the setup script: ```bash .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory - `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) -- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: -```bash -mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates -touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep -``` +**Note**: If directory already exists from define step, create missing subdirectories manually. ### Step 2: Read and Validate the Specification -1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec 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 +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate structure (name, version, summary, description, steps) +3. Check dependencies are valid and non-circular +4. Extract step details for instruction generation ### 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`. +Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. +**Guidelines**: -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- `job.yml.example` - Complete job specification example -- `step_instruction.md.example` - Complete step instruction example - -**Guidelines for generating instructions:** - -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 +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to each 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 -6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks -7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" - -### Handling Stop Hooks - -If a step in the job.yml has `stop_hooks` defined, the generated instruction file should: - -1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the stop hooks will validate -2. **Be explicit about success** - Help the agent understand when the step is truly complete -3. **Include the promise pattern** - Mention that `✓ Quality Criteria Met` should be included when criteria are met - -**Example: If the job.yml has:** -```yaml -- id: research_competitors - name: "Research Competitors" - stop_hooks: - - prompt: | - Verify the research meets criteria: - 1. Each competitor has at least 3 data points - 2. Sources are cited - 3. Information is current (within last year) -``` - -**The instruction file should include:** -```markdown -## Quality Criteria +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - When a step has user inputs, MUST use this phrase +6. **Align with hooks** - If step has `hooks` defined, match quality criteria -- Each competitor has at least 3 distinct data points -- All information is sourced with citations -- Data is current (from within the last year) -- When all criteria are met, include `✓ Quality Criteria Met` in your response -``` - -This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. - -### Using Supplementary Reference Files +**Handling Hooks**: -Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. - -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. +If a step has hooks defined, the instruction file should: +- Mirror the quality criteria that hooks will validate +- Be explicit about what success looks like +- Mention the `Quality Criteria Met` pattern when criteria are met ### Step 4: Verify job.yml Location -Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it. +Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. ### Step 5: Sync Skills -Run `deepwork sync` to generate the skills for this job: - +Run: ```bash deepwork sync ``` -This will: -- Parse the job definition -- Generate skills for each step -- Make the skills available in `.claude/skills/` (or appropriate platform directory) +This generates skills for each step in `.claude/skills/` (or platform-specific directory). -### Step 6: Consider Rules for the New Job +### Step 6: Consider Rules -After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain. +After implementing, consider whether **rules** would help enforce quality. **What are rules?** +Automated guardrails in `.deepwork/rules/` that trigger when files change. -Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure: -- Documentation stays in sync with code -- Team guidelines are followed -- Architectural decisions are respected -- Quality standards are maintained - -**When to suggest rules:** - -Think about the job you just implemented and ask: -- Does this job produce outputs that other files depend on? -- Are there documentation files that should be updated when this job's outputs change? -- Are there quality checks or reviews that should happen when certain files in this domain change? -- Could changes to the job's output files impact other parts of the project? - -**Examples of rules that might make sense:** +**When to suggest rules**: +- Job produces outputs that other files depend on +- Documentation should stay in sync with outputs +- Quality checks should happen when certain files change +**Examples**: | Job Type | Potential Rule | |----------|----------------| -| API Design | "Update API docs when endpoint definitions change" | -| Database Schema | "Review migrations when schema files change" | -| Competitive Research | "Update strategy docs when competitor analysis changes" | -| Feature Development | "Update changelog when feature files change" | -| Configuration Management | "Update install guide when config files change" | - -**How to offer rule creation:** +| API Design | Update docs when endpoints change | +| Database Schema | Review migrations when schema changes | +| Competitive Research | Update strategy when analysis changes | -If you identify one or more rules that would benefit the user, explain: -1. **What the rule would do** - What triggers it and what action it prompts -2. **Why it would help** - How it prevents common mistakes or keeps things in sync -3. **What files it would watch** - The trigger patterns - -Then ask the user: - -> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up." - -If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule. - -**Example dialogue:** - -``` -Based on the competitive_research job you just created, I noticed that when -competitor analysis files change, it would be helpful to remind you to update -your strategy documentation. - -I'd suggest a rule like: -- **Name**: "Update strategy when competitor analysis changes" -- **Trigger**: `**/positioning_report.md` -- **Action**: Prompt to review and update `docs/strategy.md` - -Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up. -``` - -**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense. - -## Example Implementation - -For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - -## Important Guidelines - -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) -- No file system errors +If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. ## 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 +Before marking complete: +- [ ] job.yml validated and in place +- [ ] All step instruction files created (complete, not stubs) +- [ ] Instructions are specific and actionable +- [ ] Output examples provided +- [ ] Quality criteria defined for each step +- [ ] User input steps use "ask structured questions" - [ ] `deepwork sync` executed successfully -- [ ] Skills generated in platform directory -- [ ] Considered whether rules would benefit this job (Step 6) -- [ ] If rules suggested, offered to run `/deepwork_rules.define` - -## 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 -- Steps with user inputs explicitly use "ask structured questions" phrasing -- Sync completed successfully -- Skills available for use -- Thoughtfully considered relevant rules for the job domain +- [ ] Skills available in platform directory +- [ ] Considered relevant rules for job domain + +## Output + +Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md index bfb393a5..bae38c0e 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -2,354 +2,137 @@ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. ## Task -Analyze the conversation history to extract learnings and improvements, then apply them appropriately: -- **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic +Analyze the conversation history to extract learnings and apply them appropriately: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md ### Step 1: Analyze Conversation for Job Executions -1. **Scan the conversation** for DeepWork slash commands that were run - - Look for patterns like `/job_name.step_id` - - Identify which jobs and steps were executed - - Note the order of execution +1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns +2. **Identify the target folder** - Deepest common folder for future work on this topic +3. **If no job specified**, ask the user which job to analyze -2. **Identify the target folder** - - This should be the deepest common folder that would contain all work on the topic in the future - - Should be clear from conversation history where work was done - - If unclear, run `git diff` to see where changes were made on the branch - -3. **If no job was specified**, ask the user: - - "Which DeepWork job would you like me to learn from?" - - List available jobs from `.deepwork/jobs/` - -### Step 2: Identify Points of Confusion and Inefficiency +### Step 2: Identify Issues Review the conversation for: -1. **Confusion signals** - - Questions the agent asked that shouldn't have been necessary - - Misunderstandings about what a step required - - Incorrect outputs that needed correction - - Ambiguous instructions that led to wrong interpretations +**Confusion signals**: +- Unnecessary questions from the agent +- Misunderstandings about step requirements +- Incorrect outputs needing correction -2. **Inefficiency signals** - - Extra steps or iterations that were needed - - Information that had to be repeated - - Context that was missing from instructions - - Dependencies that weren't clear +**Inefficiency signals**: +- Extra iterations needed +- Information repeated multiple times +- Missing context or dependencies -3. **Error patterns** - - Failed validations and why they failed - - Quality criteria that were misunderstood - - Edge cases that weren't handled +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -4. **Success patterns** - - What worked particularly well - - Efficient approaches worth preserving - - Good examples that could be added to instructions +**Success patterns**: +- What worked well +- Efficient approaches to preserve ### Step 3: Classify Learnings -For each learning identified, determine if it is: - -**Generalizable** (should improve instructions): +**Generalizable** (update instructions): - Would help ANY future run of this job - Addresses unclear or missing guidance -- Fixes incorrect assumptions in instructions -- Adds helpful examples or context -- Examples: - - "Step instructions should mention that X format is required" - - "Quality criteria should include checking for Y" - - "Add example of correct output format" - -**doc spec-Related** (should improve doc spec files): +- Adds helpful examples + +**Doc spec-related** (update doc spec files): - Improvements to document quality criteria -- Changes to document structure or format -- Updated audience or frequency information -- Examples: - - "The report should include a summary table" - - "Quality criterion 'Visualization' needs clearer requirements" - - "Documents need a section for action items" - -**Bespoke** (should go in AGENTS.md): +- Changes to document structure +- Updated audience or format info + +**Bespoke** (add to AGENTS.md): - Specific to THIS project/codebase/run -- Depends on local conventions or structure - References specific files or paths -- Would not apply to other uses of this job -- Examples: - - "In this codebase, API endpoints are in `src/api/`" - - "This project uses camelCase for function names" - - "The main config file is at `config/settings.yml`" - -### Step 3.5: Identify doc spec-Related Learnings - -Review the conversation for doc spec-related improvements: - -1. **Quality Criteria Changes** - - Were any quality criteria unclear or insufficient? - - Did the agent repeatedly fail certain criteria? - - Are there new criteria that should be added? - -2. **Document Structure Changes** - - Did the user request different sections? - - Were parts of the document format confusing? - - Should the example document be updated? - -3. **Metadata Updates** - - Has the target audience changed? - - Should frequency or path patterns be updated? - -**Signals for doc spec improvements:** -- User asked for changes to document format -- Repeated validation failures on specific criteria -- Feedback about missing sections or information -- Changes to how documents are organized/stored - -### Step 4: Update Job Instructions (Generalizable Learnings) - -For each generalizable learning: - -1. **Locate the instruction file** - - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements** - - Add missing context or clarification - - Include helpful examples - - Clarify ambiguous instructions - - Update quality criteria if needed - -3. **Keep instructions concise** - - Avoid redundancy - don't repeat the same guidance in multiple places - - Be direct - remove verbose explanations that don't add value - - Prefer bullet points over paragraphs where appropriate - -4. **Preserve instruction structure** - - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - - Add to appropriate sections rather than restructuring - - Maintain consistency with other steps - -5. **Track changes for changelog** - - Note what was changed and why - - Prepare changelog entry for job.yml +- Local conventions -### Step 4b: Extract Shared Content into Referenced Files +### Step 4: Update Job Instructions -Review all instruction files for the job and identify content that: -- Appears in multiple step instructions (duplicated) -- Is lengthy and could be extracted for clarity -- Would benefit from being maintained in one place +For generalizable learnings: -**Extract to shared files:** +1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements - add context, examples, clarify ambiguity +3. Keep instructions concise - no redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) +5. Note changes for changelog -1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` - - `conventions.md` - Coding/formatting conventions used across steps - - `examples.md` - Common examples referenced by multiple steps - - `schemas.md` - Data structures or formats used throughout +**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. -2. **Reference from instructions** using markdown includes or explicit references: - ```markdown - ## Conventions +### Step 5: Update Doc Spec Files (If Applicable) - Follow the conventions defined in `shared/conventions.md`. - ``` - -3. **Benefits of extraction:** - - Single source of truth - update once, applies everywhere - - Shorter instruction files - easier to read and maintain - - Consistent guidance across steps - -### Step 4.5: Update doc spec Files (doc spec-Related Learnings) - -If doc spec-related learnings were identified: - -1. **Locate the doc spec file** - - Find doc spec references in job.yml outputs (look for `doc_spec: .deepwork/doc_specs/[doc_spec_name].md`) - - doc spec files are at `.deepwork/doc_specs/[doc_spec_name].md` +If doc spec learnings were identified: -2. **Update quality_criteria array** - - Add new criteria with name and description - - Modify existing criteria descriptions for clarity - - Remove criteria that are no longer relevant +1. Find doc spec references in job.yml outputs +2. Update quality criteria with clearer requirements +3. Update example document if structure changed +4. Update metadata (audience, frequency, paths) -3. **Update example document** - - Modify the markdown body to reflect structure changes - - Ensure the example matches updated criteria +### Step 6: Create/Update AGENTS.md -4. **Update metadata as needed** - - target_audience: If audience has changed - - frequency: If production cadence has changed - - path_patterns: If storage location has changed +For bespoke learnings: -**Example doc spec update:** -```yaml -# Before -quality_criteria: - - name: Visualization - description: Include charts +1. **Determine location** - Deepest common folder for the topic +2. **Use file references** - Link to source files rather than duplicating content +3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` -# After -quality_criteria: - - name: Visualization - description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend +**Good patterns** (references): +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` ``` -### Step 5: Create/Update AGENTS.md (Bespoke Learnings) - -The AGENTS.md file captures project-specific knowledge that helps future agent runs. - -1. **Determine the correct location** - - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - - This ensures the knowledge is available when working in that context - - If uncertain, place at the project root - -2. **Use file references where possible** - - Instead of duplicating information, reference source files - - This keeps AGENTS.md in sync as the codebase evolves - - Pattern: "See `path/to/file.ext` for [description]" - -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. - -4. **Writing entries** - - Be concise but specific - - Always prefer file references over inline content - - Use line numbers when referencing specific code: `file.ext:42` - - Group related learnings together +**Avoid** (duplicating): +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +``` -### Step 6: Update Job Version and Changelog +### Step 7: Update Job Version and Changelog If instruction files were modified: -1. **Bump version in job.yml** - - Patch version (0.0.x) for instruction improvements - - Minor version (0.x.0) if quality criteria changed - -2. **Add changelog entry** +1. Bump version (patch for improvements, minor for criteria changes) +2. Add changelog entry: ```yaml - version: "[new_version]" - changes: "Improved [step] instructions based on execution learnings: [brief description]" + changes: "Improved [step] based on execution learnings: [brief description]" ``` -### Step 7: Sync Skills +### Step 8: Sync Skills -**Run deepwork sync** (if instructions were modified) +If instructions were modified: ```bash deepwork sync ``` -## File Reference Patterns - -When adding entries to AGENTS.md, prefer these patterns: - -**Good (references)**: -```markdown -- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` -- Configuration schema: Defined in `config/schema.json` -``` - -**Avoid (duplicating)**: -```markdown -- API endpoints should return JSON with this format: { status: ..., data: ... } -- Error handling should use try/catch with custom error classes -- Configuration requires these fields: name, version, ... -``` - ## Quality Criteria -- Conversation has been analyzed for job executions -- Points of confusion and inefficiency are identified -- Learnings are correctly classified (generalizable vs bespoke) -- Job instructions updated for generalizable improvements -- Instructions are concise - no redundancy or unnecessary verbosity -- Shared/lengthy content extracted into referenced files where appropriate -- AGENTS.md created/updated with bespoke learnings -- File references used instead of duplicating content -- AGENTS.md is in the correct folder (the deepest common folder for the topic) -- When all criteria are met, include `✓ Quality Criteria Met` - -## Example Dialog - -``` -User: /deepwork_jobs.learn - -Claude: I'll analyze this conversation for learnings from DeepWork job executions. - -**Conversation Analysis** - -I found the following job executions: -1. `/competitive_research.identify_competitors` - Completed -2. `/competitive_research.research_competitors` - Completed with 2 iterations -3. `/competitive_research.comparative_analysis` - Completed - -**Identified Issues** - -1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. - -2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. - -**Classification** - -- Generalizable: Add pricing to research requirements in instructions -- Bespoke: This project focuses on B2B SaaS in the HR tech space - -**Actions Taken** - -1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: - - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements - - Added note about carrying forward industry context from previous step - -2. Created `./competitive_research_output/AGENTS.md`: - ```markdown - # Project Context for Competitive Research - - ## Job-Specific Context - - ### competitive_research - - #### Industry Focus - - Domain: B2B SaaS, HR Technology sector - - See `identify_competitors_output.md` for market definition - - #### Competitors Identified - - Reference: `competitor_list.md` for full details - - ## Last Updated - - Date: 2024-01-15 - - From conversation about: Initial competitive analysis run - ``` - -3. Updated job.yml version to 1.0.1 with changelog entry - -4. Ran `deepwork sync` - -**Summary** - -Updated job instructions and created AGENTS.md with bespoke learnings. -``` +- Conversation analyzed for job executions +- Learnings correctly classified (generalizable vs bespoke) +- Instructions updated for generalizable improvements +- Instructions remain concise +- Shared content extracted where appropriate +- AGENTS.md in correct folder with file references +- Sync complete if instructions modified +- When complete: `Quality Criteria Met` -## Handling Edge Cases +## Edge Cases -**No job executions found**: -- Ask user which job they'd like to analyze -- Or offer to review available jobs +**No job executions found**: Ask user which job to analyze -**Multiple jobs executed**: -- Analyze each job separately -- Create separate AGENTS.md entries or files as appropriate +**Multiple jobs executed**: Analyze each separately -**AGENTS.md already exists**: -- Read existing content -- Append new learnings to appropriate sections -- Update "Last Updated" section +**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" -**No issues found**: -- Document what worked well -- Consider if any successful patterns should be added to instructions as examples +**No issues found**: Document what worked well, consider adding as examples -**Sensitive information**: -- Never include secrets, credentials, or PII in AGENTS.md -- Reference config files instead of including values +**Sensitive information**: Never include secrets or PII - reference config files instead diff --git a/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md b/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md index fcc0ae9c..87a2d7a9 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md +++ b/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md @@ -2,207 +2,105 @@ ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass. +Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. ### Step 1: Read the Job Specification -Read the `job.yml` file created in the define step: - -``` -.deepwork/jobs/[job_name]/job.yml -``` - -Also read the doc spec for reference: - -``` -.deepwork/doc_specs/job_spec.md -``` +Read both files: +- `.deepwork/jobs/[job_name]/job.yml` - The specification to review +- `.deepwork/doc_specs/job_spec.md` - The quality criteria ### Step 2: Spawn Review Sub-Agent -Use the Task tool to spawn a sub-agent that will provide an unbiased review: +Use the Task tool with: +- `subagent_type`: "general-purpose" +- `model`: "haiku" +- `description`: "Review job.yml against doc spec" -``` -Task tool parameters: -- subagent_type: "general-purpose" -- model: "haiku" -- description: "Review job.yml against doc spec" -- prompt: [see below] -``` - -**Sub-agent prompt template:** +**Sub-agent prompt**: ``` -Review this job.yml against the following 9 quality criteria from the doc spec. +Review this job.yml against the following 9 quality criteria. -For each criterion, respond with: -- PASS or FAIL -- If FAIL: specific issue and suggested fix +For each criterion, respond with PASS or FAIL. +If FAIL: provide the specific issue and suggested fix. ## job.yml Content -[paste the full job.yml content here] +[paste full job.yml content] ## Quality Criteria -1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`) - -2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`) - -3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes - -4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users - -5. **Changelog Present**: Must include a changelog array with at least the initial version entry - -6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array - -7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references - -8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array - -9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`) +1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) +2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) +3. **Concise Summary**: Under 200 characters, describes what job accomplishes +4. **Rich Description**: Multi-line explaining problem, process, outcomes, users +5. **Changelog Present**: Array with at least initial version entry +6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: Reference existing step IDs, no circular references +8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies +9. **Output Paths**: Valid filenames or paths ## Response Format -Respond with a structured evaluation: - ### Overall: [X/9 PASS] ### Criterion Results - 1. Valid Identifier: [PASS/FAIL] [If FAIL: Issue and fix] - -2. Semantic Version: [PASS/FAIL] - [If FAIL: Issue and fix] - -[... continue for all 9 criteria ...] +... ### Summary of Required Fixes - -[List any fixes needed, or "No fixes required - all criteria pass"] +[List fixes needed, or "No fixes required"] ``` -### Step 3: Review Sub-Agent Findings +### Step 3: Review Findings Parse the sub-agent's response: - -1. **Count passing criteria** - How many of the 9 criteria passed? -2. **Identify failures** - List specific criteria that failed -3. **Note suggested fixes** - What changes does the sub-agent recommend? +1. Count passing criteria +2. Identify failures +3. Note suggested fixes ### Step 4: Fix Failed Criteria -For each failed criterion, edit the job.yml to address the issue: +Edit job.yml to address each failure: -**Common fixes by criterion:** - -| Criterion | Common Issue | Fix | -|-----------|-------------|-----| -| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | -| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format | -| Concise Summary | Too long or vague | Shorten to <200 chars, be specific | -| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users | -| Changelog Present | Missing changelog | Add `changelog:` with initial version entry | -| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies | -| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies | -| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array | -| Output Paths | Invalid characters or format | Use valid filename/path format | +| Criterion | Common Fix | +|-----------|-----------| +| Valid Identifier | Convert to lowercase_underscores | +| Semantic Version | Set to `"1.0.0"` or fix format | +| Concise Summary | Shorten to <200 chars | +| Rich Description | Add multi-line explanation | +| Changelog Present | Add `changelog:` array | +| Complete Steps | Add missing required fields | +| Valid Dependencies | Fix step ID reference | +| Input Consistency | Add referenced step to dependencies | +| Output Paths | Use valid filename/path format | ### Step 5: Re-Run Review (If Needed) If any criteria failed: - -1. **Spawn a new sub-agent** with the updated job.yml content -2. **Review the new findings** -3. **Fix any remaining issues** -4. **Repeat until all 9 criteria pass** +1. Spawn a new sub-agent with updated job.yml +2. Review new findings +3. Fix remaining issues +4. Repeat until all 9 criteria pass ### Step 6: Confirm Completion When all 9 criteria pass: -1. **Announce success**: "All 9 doc spec quality criteria pass." -2. **List what was validated**: - - Valid Identifier - - Semantic Version - - Concise Summary - - Rich Description - - Changelog Present - - Complete Steps - - Valid Dependencies - - Input Consistency - - Output Paths -3. **Include the promise**: `Quality Criteria Met` -4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files." - -## Example Review Cycle - -``` -Claude: Let me review the job.yml against the doc spec quality criteria. - -[Spawns sub-agent with haiku model] - -Sub-agent response: -### Overall: 7/9 PASS - -### Criterion Results -1. Valid Identifier: PASS -2. Semantic Version: PASS -3. Concise Summary: FAIL - Issue: Summary is 245 characters, exceeds 200 char limit - Fix: Shorten to "Competitive analysis workflow for product positioning" -4. Rich Description: PASS -5. Changelog Present: FAIL - Issue: No changelog array present - Fix: Add changelog with initial version entry -6. Complete Steps: PASS -7. Valid Dependencies: PASS -8. Input Consistency: PASS -9. Output Paths: PASS - -### Summary of Required Fixes -1. Shorten summary to under 200 characters -2. Add changelog array with initial version - -Claude: I found 2 issues. Let me fix them. - -[Edits job.yml to shorten summary and add changelog] - -Claude: Let me verify the fixes with another review. - -[Spawns new sub-agent] - -Sub-agent response: -### Overall: 9/9 PASS - -### Summary of Required Fixes -No fixes required - all criteria pass - -Claude: All 9 doc spec quality criteria pass. - -Quality Criteria Met - -**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files. -``` - -## Quality Criteria - -- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review) -- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec -- **Findings Addressed**: All failed criteria were fixed by the main agent -- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed -- **Promise Included**: The response includes `Quality Criteria Met` when complete +1. Announce: "All 9 doc spec quality criteria pass." +2. Include: `Quality Criteria Met` +3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 8a705168..68e1cd17 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -22,462 +22,119 @@ prompt = """ ## 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. +Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. ## Task Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. - -The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). +The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. ### Step 1: Understand the Job Purpose -Start by asking structured questions to understand what the user wants to accomplish: +Ask structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? - 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 1.5: Detect Document-Oriented Workflows +### Step 2: Detect Document-Oriented Workflows -**Check for document-focused patterns** in the user's description: -- Keywords: "report", "summary", "document", "create", "monthly", "quarterly", "for stakeholders", "for leadership" -- Final deliverable is a specific document (e.g., "AWS spending report", "competitive analysis", "sprint summary") +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly" +- Final deliverable is a specific document type - Recurring documents with consistent structure -**If a document-oriented workflow is detected:** - -1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first to ensure consistent quality." +**If detected**, inform the user and ask if they want to: +- Create a doc spec for consistent document quality +- Use an existing doc spec from `.deepwork/doc_specs/` +- Skip doc spec and proceed with simple outputs -2. Ask structured questions to understand if they want to: - - Create a doc spec for this document - - Use an existing doc spec (if any exist in `.deepwork/doc_specs/`) - - Skip doc spec and proceed with simple outputs +See the expert's documentation on doc specs for the full schema and examples. -### Step 1.6: Define the Doc Spec (if needed) +### Step 3: Define Each Step -When creating a doc spec, gather the following information: +For each major phase, gather: -1. **Document Identity** - - What is the document called? (e.g., "Monthly AWS Spending Report") - - Brief description of its purpose - - Where should these documents be stored? (path patterns like `finance/aws-reports/*.md`) +1. **Step Purpose**: What does this step accomplish? +2. **Inputs**: User parameters or files from previous steps +3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) +4. **Dependencies**: Which previous steps must complete first? +5. **Quality Criteria**: What makes a good vs. bad output? +6. **Agent Delegation**: Should this step run in a forked context? -2. **Audience and Context** - - Who reads this document? (target audience) - - How often is it produced? (frequency) +#### Work Product Storage Guidelines -3. **Quality Criteria** (3-5 criteria, each with name and description) - - **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve. +Job outputs belong in the main repository directory structure, not in dot-directories. - Examples for a spending report: - - **Visualization**: Must include charts showing spend breakdown by service - - **Variance Analysis**: Must compare current month against previous with percentages - - **Action Items**: Must include recommended cost optimization actions - - **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible. - -4. **Document Structure** - - What sections should it have? - - Any required elements (tables, charts, summaries)? - -### Step 1.7: Create the doc spec File (if needed) - -Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`: - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure. - -**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files). - -After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output. - -### Step 2: Define Each Step - -For each major phase they mentioned, ask structured questions to gather details: - -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? - - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output - - #### Work Product Storage Guidelines - - **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only. - - **Why this matters**: - - **Version control**: Work products in the main repo are tracked by git and visible in PRs - - **Discoverability**: Team members can find outputs without knowing about DeepWork internals - - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths - - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`) - - **Good output path patterns**: - ``` - competitive_research/competitors_list.md - competitive_research/acme_corp/research.md - operations/reports/2026-01/spending_analysis.md - docs/api/endpoints.md - ``` - - **Avoid these patterns**: - ``` - .deepwork/outputs/report.md # Hidden in dot-directory - output.md # Too generic, no context - research.md # Unclear which research - temp/draft.md # Transient-sounding paths - ``` - - **Organizing multi-file outputs**: - - Use the job name as a top-level folder when outputs are job-specific - - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/` - - Match existing project conventions when extending a codebase - - **When to include dates in paths**: - - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful. - ``` - operations/reports/2026-01/spending_analysis.md # Monthly report - keep history - hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf # Per-employee quarterly review - ``` - - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files. - ``` - competitive_research/acme_corp/swot.md # Current SWOT - updated over time - docs/architecture/overview.md # Living document - ``` - - **Supporting materials and intermediate outputs**: - - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output - - Name the dataroom folder by replacing the file extension with `_dataroom` - ``` - operations/reports/2026-01/spending_analysis.md # Final output - operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials - raw_data.csv - vendor_breakdown.md - notes.md - ``` - - This keeps supporting materials organized and discoverable without cluttering the main output location - -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? - -6. **Agent Delegation** (optional) - - Should this step be executed by a specific agent type? - - Use the `agent` field when the step should run in a forked context with a specific agent - - When `agent` is set, the generated skill automatically includes `context: fork` - - Available agent types: - - `general-purpose` - Standard agent for multi-step tasks - - ```yaml - steps: - - id: research_step - agent: general-purpose # Delegates to the general-purpose agent - ``` - -**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. - -#### Doc Spec-Aware Output Format - -When a step produces a document with a doc spec reference, use this format in job.yml: - -```yaml -outputs: - - file: reports/monthly_spending.md - doc_spec: .deepwork/doc_specs/monthly_aws_report.md +**Good patterns**: ``` - -The doc spec's quality criteria will automatically be included in the generated skill, ensuring consistent document quality. - -### Capability Considerations - -When defining steps, identify any that require specialized tools: - -**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. - -### Step 3: Validate the Workflow - -After gathering information about all steps: - -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: Define Quality Validation (Stop Hooks) - -For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. - -**Ask structured questions about quality validation:** -- "Are there specific quality criteria that must be met for this step?" -- "Would you like the agent to validate its work before completing?" -- "What would make you send the work back for revision?" - -**Stop hooks are particularly valuable for:** -- Steps with complex outputs that need multiple checks -- Steps where quality is critical (final deliverables) -- Steps with subjective quality criteria that benefit from AI self-review - -**Three types of stop hooks are supported:** - -1. **Inline Prompt** (`prompt`) - Best for simple quality criteria - ```yaml - stop_hooks: - - prompt: | - Verify the output meets these criteria: - 1. Contains at least 5 competitors - 2. Each competitor has a description - 3. Selection rationale is clear - ``` - -2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - -3. **Script** (`script`) - For programmatic validation (tests, linting) - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -**Multiple hooks can be combined:** -```yaml -stop_hooks: - - script: hooks/lint_output.sh - - prompt: "Verify the content is comprehensive and well-organized" +competitive_research/competitors_list.md +operations/reports/2026-01/spending_analysis.md ``` -**Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). - -### Step 5: Create the Job Directory and Specification - -Only after you have complete understanding, create the job directory and `job.yml` file: - -**First, create the directory structure** using the `make_new_job.sh` script: - -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +**Avoid**: ``` - -This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory -- `.deepwork/jobs/[job_name]/steps/` - For step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts -- `.deepwork/jobs/[job_name]/templates/` - For example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance - -**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) - -**Doc Spec**: See `.deepwork/doc_specs/job_spec.md` for the complete specification with quality criteria. - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. - -**Important**: -- Use lowercase with underscores for job name and step IDs -- Ensure file inputs reference steps in dependencies -- 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 -- Include a `changelog` section with an initial entry for version 1.0.0 - -## Example Dialog - +.deepwork/outputs/report.md # Hidden in dot-directory +output.md # Too generic ``` -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? +**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. -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 in the project root, or in a subdirectory like `research/` or `data/`? - -User: Just call it `competitors_list.md` in the project root. - -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! +**Supporting materials**: Place in `_dataroom` folder as peer to final output: +``` +operations/reports/2026-01/spending_analysis.md +operations/reports/2026-01/spending_analysis_dataroom/ + raw_data.csv + notes.md +``` -Claude: Great! Creating the job.yml specification now... +### Step 4: Validate the Workflow -[Creates .deepwork/jobs/competitive_research/job.yml with the complete spec] +After gathering all information: -✓ Job specification created! +1. **Review the flow** - Summarize and show how outputs feed into the next step +2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies +3. **Confirm details** - Job name, summary (max 200 chars), description, version -**File created:** -- .deepwork/jobs/competitive_research/job.yml +### Step 5: Create the Job Specification -**Next step:** -Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria. +**First, create the directory structure**: +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` -## Important Guidelines - -1. **Focus on specification only** - Don't create instruction files yet -2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool -3. **Rich context in description** - This helps with future refinement -4. **Validate understanding** - Summarize and confirm before creating -5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed +**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` -## 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 +Refer to the expert for the complete job.yml schema. Key validation rules: +- Job name: lowercase, underscores only, no spaces +- Version: semantic versioning (start with 1.0.0) +- Summary: max 200 characters - 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 +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example -The complete YAML specification file (example shown in Step 5 above). +## Output -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the new job being created) +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. After creating the file: 1. Inform the user that the specification is complete -2. Recommend that they review the job.yml file +2. Recommend they review the job.yml file 3. Tell them to run `/deepwork_jobs.review_job_spec` next - ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml index 484f4bcc..368ee3e2 100644 --- a/.gemini/skills/deepwork_jobs/implement.toml +++ b/.gemini/skills/deepwork_jobs/implement.toml @@ -26,235 +26,108 @@ Before proceeding, confirm these steps are complete: ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. +Read the `job.yml` specification and create all necessary files to make the job functional. -### Step 1: Create Directory Structure Using Script - -Run the `make_new_job.sh` script to create the standard directory structure: +### Step 1: Create Directory Structure +Run the setup script: ```bash .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory - `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) -- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: -```bash -mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates -touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep -``` +**Note**: If directory already exists from define step, create missing subdirectories manually. ### Step 2: Read and Validate the Specification -1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec 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 +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate structure (name, version, summary, description, steps) +3. Check dependencies are valid and non-circular +4. Extract step details for instruction generation ### 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`. +Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. +**Guidelines**: -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- `job.yml.example` - Complete job specification example -- `step_instruction.md.example` - Complete step instruction example - -**Guidelines for generating instructions:** - -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 +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to each 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 -6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks -7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" - -### Handling Stop Hooks - -If a step in the job.yml has `stop_hooks` defined, the generated instruction file should: - -1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the stop hooks will validate -2. **Be explicit about success** - Help the agent understand when the step is truly complete -3. **Include the promise pattern** - Mention that `✓ Quality Criteria Met` should be included when criteria are met - -**Example: If the job.yml has:** -```yaml -- id: research_competitors - name: "Research Competitors" - stop_hooks: - - prompt: | - Verify the research meets criteria: - 1. Each competitor has at least 3 data points - 2. Sources are cited - 3. Information is current (within last year) -``` - -**The instruction file should include:** -```markdown -## Quality Criteria +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - When a step has user inputs, MUST use this phrase +6. **Align with hooks** - If step has `hooks` defined, match quality criteria -- Each competitor has at least 3 distinct data points -- All information is sourced with citations -- Data is current (from within the last year) -- When all criteria are met, include `✓ Quality Criteria Met` in your response -``` - -This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. - -### Using Supplementary Reference Files +**Handling Hooks**: -Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. - -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. +If a step has hooks defined, the instruction file should: +- Mirror the quality criteria that hooks will validate +- Be explicit about what success looks like +- Mention the `Quality Criteria Met` pattern when criteria are met ### Step 4: Verify job.yml Location -Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it. +Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. ### Step 5: Sync Skills -Run `deepwork sync` to generate the skills for this job: - +Run: ```bash deepwork sync ``` -This will: -- Parse the job definition -- Generate skills for each step -- Make the skills available in `.claude/skills/` (or appropriate platform directory) +This generates skills for each step in `.claude/skills/` (or platform-specific directory). -### Step 6: Consider Rules for the New Job +### Step 6: Consider Rules -After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain. +After implementing, consider whether **rules** would help enforce quality. **What are rules?** +Automated guardrails in `.deepwork/rules/` that trigger when files change. -Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure: -- Documentation stays in sync with code -- Team guidelines are followed -- Architectural decisions are respected -- Quality standards are maintained - -**When to suggest rules:** - -Think about the job you just implemented and ask: -- Does this job produce outputs that other files depend on? -- Are there documentation files that should be updated when this job's outputs change? -- Are there quality checks or reviews that should happen when certain files in this domain change? -- Could changes to the job's output files impact other parts of the project? - -**Examples of rules that might make sense:** +**When to suggest rules**: +- Job produces outputs that other files depend on +- Documentation should stay in sync with outputs +- Quality checks should happen when certain files change +**Examples**: | Job Type | Potential Rule | |----------|----------------| -| API Design | "Update API docs when endpoint definitions change" | -| Database Schema | "Review migrations when schema files change" | -| Competitive Research | "Update strategy docs when competitor analysis changes" | -| Feature Development | "Update changelog when feature files change" | -| Configuration Management | "Update install guide when config files change" | - -**How to offer rule creation:** +| API Design | Update docs when endpoints change | +| Database Schema | Review migrations when schema changes | +| Competitive Research | Update strategy when analysis changes | -If you identify one or more rules that would benefit the user, explain: -1. **What the rule would do** - What triggers it and what action it prompts -2. **Why it would help** - How it prevents common mistakes or keeps things in sync -3. **What files it would watch** - The trigger patterns - -Then ask the user: - -> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up." - -If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule. - -**Example dialogue:** - -``` -Based on the competitive_research job you just created, I noticed that when -competitor analysis files change, it would be helpful to remind you to update -your strategy documentation. - -I'd suggest a rule like: -- **Name**: "Update strategy when competitor analysis changes" -- **Trigger**: `**/positioning_report.md` -- **Action**: Prompt to review and update `docs/strategy.md` - -Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up. -``` - -**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense. - -## Example Implementation - -For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - -## Important Guidelines - -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) -- No file system errors +If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. ## 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 +Before marking complete: +- [ ] job.yml validated and in place +- [ ] All step instruction files created (complete, not stubs) +- [ ] Instructions are specific and actionable +- [ ] Output examples provided +- [ ] Quality criteria defined for each step +- [ ] User input steps use "ask structured questions" - [ ] `deepwork sync` executed successfully -- [ ] Skills generated in platform directory -- [ ] Considered whether rules would benefit this job (Step 6) -- [ ] If rules suggested, offered to run `/deepwork_rules.define` - -## 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 -- Steps with user inputs explicitly use "ask structured questions" phrasing -- Sync completed successfully -- Skills available for use -- Thoughtfully considered relevant rules for the job domain +- [ ] Skills available in platform directory +- [ ] Considered relevant rules for job domain + +## Output + +Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. ### Job Context diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index ef16944b..23ea6c61 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -22,357 +22,140 @@ prompt = """ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. ## Task -Analyze the conversation history to extract learnings and improvements, then apply them appropriately: -- **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic +Analyze the conversation history to extract learnings and apply them appropriately: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md ### Step 1: Analyze Conversation for Job Executions -1. **Scan the conversation** for DeepWork slash commands that were run - - Look for patterns like `/job_name.step_id` - - Identify which jobs and steps were executed - - Note the order of execution +1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns +2. **Identify the target folder** - Deepest common folder for future work on this topic +3. **If no job specified**, ask the user which job to analyze -2. **Identify the target folder** - - This should be the deepest common folder that would contain all work on the topic in the future - - Should be clear from conversation history where work was done - - If unclear, run `git diff` to see where changes were made on the branch - -3. **If no job was specified**, ask the user: - - "Which DeepWork job would you like me to learn from?" - - List available jobs from `.deepwork/jobs/` - -### Step 2: Identify Points of Confusion and Inefficiency +### Step 2: Identify Issues Review the conversation for: -1. **Confusion signals** - - Questions the agent asked that shouldn't have been necessary - - Misunderstandings about what a step required - - Incorrect outputs that needed correction - - Ambiguous instructions that led to wrong interpretations +**Confusion signals**: +- Unnecessary questions from the agent +- Misunderstandings about step requirements +- Incorrect outputs needing correction -2. **Inefficiency signals** - - Extra steps or iterations that were needed - - Information that had to be repeated - - Context that was missing from instructions - - Dependencies that weren't clear +**Inefficiency signals**: +- Extra iterations needed +- Information repeated multiple times +- Missing context or dependencies -3. **Error patterns** - - Failed validations and why they failed - - Quality criteria that were misunderstood - - Edge cases that weren't handled +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -4. **Success patterns** - - What worked particularly well - - Efficient approaches worth preserving - - Good examples that could be added to instructions +**Success patterns**: +- What worked well +- Efficient approaches to preserve ### Step 3: Classify Learnings -For each learning identified, determine if it is: - -**Generalizable** (should improve instructions): +**Generalizable** (update instructions): - Would help ANY future run of this job - Addresses unclear or missing guidance -- Fixes incorrect assumptions in instructions -- Adds helpful examples or context -- Examples: - - "Step instructions should mention that X format is required" - - "Quality criteria should include checking for Y" - - "Add example of correct output format" - -**doc spec-Related** (should improve doc spec files): +- Adds helpful examples + +**Doc spec-related** (update doc spec files): - Improvements to document quality criteria -- Changes to document structure or format -- Updated audience or frequency information -- Examples: - - "The report should include a summary table" - - "Quality criterion 'Visualization' needs clearer requirements" - - "Documents need a section for action items" - -**Bespoke** (should go in AGENTS.md): +- Changes to document structure +- Updated audience or format info + +**Bespoke** (add to AGENTS.md): - Specific to THIS project/codebase/run -- Depends on local conventions or structure - References specific files or paths -- Would not apply to other uses of this job -- Examples: - - "In this codebase, API endpoints are in `src/api/`" - - "This project uses camelCase for function names" - - "The main config file is at `config/settings.yml`" - -### Step 3.5: Identify doc spec-Related Learnings - -Review the conversation for doc spec-related improvements: - -1. **Quality Criteria Changes** - - Were any quality criteria unclear or insufficient? - - Did the agent repeatedly fail certain criteria? - - Are there new criteria that should be added? - -2. **Document Structure Changes** - - Did the user request different sections? - - Were parts of the document format confusing? - - Should the example document be updated? - -3. **Metadata Updates** - - Has the target audience changed? - - Should frequency or path patterns be updated? - -**Signals for doc spec improvements:** -- User asked for changes to document format -- Repeated validation failures on specific criteria -- Feedback about missing sections or information -- Changes to how documents are organized/stored - -### Step 4: Update Job Instructions (Generalizable Learnings) - -For each generalizable learning: - -1. **Locate the instruction file** - - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements** - - Add missing context or clarification - - Include helpful examples - - Clarify ambiguous instructions - - Update quality criteria if needed - -3. **Keep instructions concise** - - Avoid redundancy - don't repeat the same guidance in multiple places - - Be direct - remove verbose explanations that don't add value - - Prefer bullet points over paragraphs where appropriate - -4. **Preserve instruction structure** - - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - - Add to appropriate sections rather than restructuring - - Maintain consistency with other steps - -5. **Track changes for changelog** - - Note what was changed and why - - Prepare changelog entry for job.yml +- Local conventions -### Step 4b: Extract Shared Content into Referenced Files +### Step 4: Update Job Instructions -Review all instruction files for the job and identify content that: -- Appears in multiple step instructions (duplicated) -- Is lengthy and could be extracted for clarity -- Would benefit from being maintained in one place +For generalizable learnings: -**Extract to shared files:** +1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements - add context, examples, clarify ambiguity +3. Keep instructions concise - no redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) +5. Note changes for changelog -1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` - - `conventions.md` - Coding/formatting conventions used across steps - - `examples.md` - Common examples referenced by multiple steps - - `schemas.md` - Data structures or formats used throughout +**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. -2. **Reference from instructions** using markdown includes or explicit references: - ```markdown - ## Conventions +### Step 5: Update Doc Spec Files (If Applicable) - Follow the conventions defined in `shared/conventions.md`. - ``` - -3. **Benefits of extraction:** - - Single source of truth - update once, applies everywhere - - Shorter instruction files - easier to read and maintain - - Consistent guidance across steps - -### Step 4.5: Update doc spec Files (doc spec-Related Learnings) - -If doc spec-related learnings were identified: - -1. **Locate the doc spec file** - - Find doc spec references in job.yml outputs (look for `doc_spec: .deepwork/doc_specs/[doc_spec_name].md`) - - doc spec files are at `.deepwork/doc_specs/[doc_spec_name].md` +If doc spec learnings were identified: -2. **Update quality_criteria array** - - Add new criteria with name and description - - Modify existing criteria descriptions for clarity - - Remove criteria that are no longer relevant +1. Find doc spec references in job.yml outputs +2. Update quality criteria with clearer requirements +3. Update example document if structure changed +4. Update metadata (audience, frequency, paths) -3. **Update example document** - - Modify the markdown body to reflect structure changes - - Ensure the example matches updated criteria +### Step 6: Create/Update AGENTS.md -4. **Update metadata as needed** - - target_audience: If audience has changed - - frequency: If production cadence has changed - - path_patterns: If storage location has changed +For bespoke learnings: -**Example doc spec update:** -```yaml -# Before -quality_criteria: - - name: Visualization - description: Include charts +1. **Determine location** - Deepest common folder for the topic +2. **Use file references** - Link to source files rather than duplicating content +3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` -# After -quality_criteria: - - name: Visualization - description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend +**Good patterns** (references): +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` ``` -### Step 5: Create/Update AGENTS.md (Bespoke Learnings) - -The AGENTS.md file captures project-specific knowledge that helps future agent runs. - -1. **Determine the correct location** - - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - - This ensures the knowledge is available when working in that context - - If uncertain, place at the project root - -2. **Use file references where possible** - - Instead of duplicating information, reference source files - - This keeps AGENTS.md in sync as the codebase evolves - - Pattern: "See `path/to/file.ext` for [description]" - -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. - -4. **Writing entries** - - Be concise but specific - - Always prefer file references over inline content - - Use line numbers when referencing specific code: `file.ext:42` - - Group related learnings together +**Avoid** (duplicating): +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +``` -### Step 6: Update Job Version and Changelog +### Step 7: Update Job Version and Changelog If instruction files were modified: -1. **Bump version in job.yml** - - Patch version (0.0.x) for instruction improvements - - Minor version (0.x.0) if quality criteria changed - -2. **Add changelog entry** +1. Bump version (patch for improvements, minor for criteria changes) +2. Add changelog entry: ```yaml - version: "[new_version]" - changes: "Improved [step] instructions based on execution learnings: [brief description]" + changes: "Improved [step] based on execution learnings: [brief description]" ``` -### Step 7: Sync Skills +### Step 8: Sync Skills -**Run deepwork sync** (if instructions were modified) +If instructions were modified: ```bash deepwork sync ``` -## File Reference Patterns - -When adding entries to AGENTS.md, prefer these patterns: - -**Good (references)**: -```markdown -- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` -- Configuration schema: Defined in `config/schema.json` -``` - -**Avoid (duplicating)**: -```markdown -- API endpoints should return JSON with this format: { status: ..., data: ... } -- Error handling should use try/catch with custom error classes -- Configuration requires these fields: name, version, ... -``` - ## Quality Criteria -- Conversation has been analyzed for job executions -- Points of confusion and inefficiency are identified -- Learnings are correctly classified (generalizable vs bespoke) -- Job instructions updated for generalizable improvements -- Instructions are concise - no redundancy or unnecessary verbosity -- Shared/lengthy content extracted into referenced files where appropriate -- AGENTS.md created/updated with bespoke learnings -- File references used instead of duplicating content -- AGENTS.md is in the correct folder (the deepest common folder for the topic) -- When all criteria are met, include `✓ Quality Criteria Met` - -## Example Dialog - -``` -User: /deepwork_jobs.learn - -Claude: I'll analyze this conversation for learnings from DeepWork job executions. - -**Conversation Analysis** - -I found the following job executions: -1. `/competitive_research.identify_competitors` - Completed -2. `/competitive_research.research_competitors` - Completed with 2 iterations -3. `/competitive_research.comparative_analysis` - Completed - -**Identified Issues** - -1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. - -2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. - -**Classification** - -- Generalizable: Add pricing to research requirements in instructions -- Bespoke: This project focuses on B2B SaaS in the HR tech space - -**Actions Taken** - -1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: - - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements - - Added note about carrying forward industry context from previous step - -2. Created `./competitive_research_output/AGENTS.md`: - ```markdown - # Project Context for Competitive Research - - ## Job-Specific Context - - ### competitive_research - - #### Industry Focus - - Domain: B2B SaaS, HR Technology sector - - See `identify_competitors_output.md` for market definition - - #### Competitors Identified - - Reference: `competitor_list.md` for full details - - ## Last Updated - - Date: 2024-01-15 - - From conversation about: Initial competitive analysis run - ``` - -3. Updated job.yml version to 1.0.1 with changelog entry - -4. Ran `deepwork sync` - -**Summary** - -Updated job instructions and created AGENTS.md with bespoke learnings. -``` +- Conversation analyzed for job executions +- Learnings correctly classified (generalizable vs bespoke) +- Instructions updated for generalizable improvements +- Instructions remain concise +- Shared content extracted where appropriate +- AGENTS.md in correct folder with file references +- Sync complete if instructions modified +- When complete: `Quality Criteria Met` -## Handling Edge Cases +## Edge Cases -**No job executions found**: -- Ask user which job they'd like to analyze -- Or offer to review available jobs +**No job executions found**: Ask user which job to analyze -**Multiple jobs executed**: -- Analyze each job separately -- Create separate AGENTS.md entries or files as appropriate +**Multiple jobs executed**: Analyze each separately -**AGENTS.md already exists**: -- Read existing content -- Append new learnings to appropriate sections -- Update "Last Updated" section +**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" -**No issues found**: -- Document what worked well -- Consider if any successful patterns should be added to instructions as examples +**No issues found**: Document what worked well, consider adding as examples -**Sensitive information**: -- Never include secrets, credentials, or PII in AGENTS.md -- Reference config files instead of including values +**Sensitive information**: Never include secrets or PII - reference config files instead ### Job Context diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index 265eb151..1fa1e2c5 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -26,210 +26,108 @@ Before proceeding, confirm these steps are complete: ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass. +Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. ### Step 1: Read the Job Specification -Read the `job.yml` file created in the define step: - -``` -.deepwork/jobs/[job_name]/job.yml -``` - -Also read the doc spec for reference: - -``` -.deepwork/doc_specs/job_spec.md -``` +Read both files: +- `.deepwork/jobs/[job_name]/job.yml` - The specification to review +- `.deepwork/doc_specs/job_spec.md` - The quality criteria ### Step 2: Spawn Review Sub-Agent -Use the Task tool to spawn a sub-agent that will provide an unbiased review: +Use the Task tool with: +- `subagent_type`: "general-purpose" +- `model`: "haiku" +- `description`: "Review job.yml against doc spec" -``` -Task tool parameters: -- subagent_type: "general-purpose" -- model: "haiku" -- description: "Review job.yml against doc spec" -- prompt: [see below] -``` - -**Sub-agent prompt template:** +**Sub-agent prompt**: ``` -Review this job.yml against the following 9 quality criteria from the doc spec. +Review this job.yml against the following 9 quality criteria. -For each criterion, respond with: -- PASS or FAIL -- If FAIL: specific issue and suggested fix +For each criterion, respond with PASS or FAIL. +If FAIL: provide the specific issue and suggested fix. ## job.yml Content -[paste the full job.yml content here] +[paste full job.yml content] ## Quality Criteria -1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`) - -2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`) - -3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes - -4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users - -5. **Changelog Present**: Must include a changelog array with at least the initial version entry - -6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array - -7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references - -8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array - -9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`) +1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) +2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) +3. **Concise Summary**: Under 200 characters, describes what job accomplishes +4. **Rich Description**: Multi-line explaining problem, process, outcomes, users +5. **Changelog Present**: Array with at least initial version entry +6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: Reference existing step IDs, no circular references +8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies +9. **Output Paths**: Valid filenames or paths ## Response Format -Respond with a structured evaluation: - ### Overall: [X/9 PASS] ### Criterion Results - 1. Valid Identifier: [PASS/FAIL] [If FAIL: Issue and fix] - -2. Semantic Version: [PASS/FAIL] - [If FAIL: Issue and fix] - -[... continue for all 9 criteria ...] +... ### Summary of Required Fixes - -[List any fixes needed, or "No fixes required - all criteria pass"] +[List fixes needed, or "No fixes required"] ``` -### Step 3: Review Sub-Agent Findings +### Step 3: Review Findings Parse the sub-agent's response: - -1. **Count passing criteria** - How many of the 9 criteria passed? -2. **Identify failures** - List specific criteria that failed -3. **Note suggested fixes** - What changes does the sub-agent recommend? +1. Count passing criteria +2. Identify failures +3. Note suggested fixes ### Step 4: Fix Failed Criteria -For each failed criterion, edit the job.yml to address the issue: +Edit job.yml to address each failure: -**Common fixes by criterion:** - -| Criterion | Common Issue | Fix | -|-----------|-------------|-----| -| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | -| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format | -| Concise Summary | Too long or vague | Shorten to <200 chars, be specific | -| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users | -| Changelog Present | Missing changelog | Add `changelog:` with initial version entry | -| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies | -| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies | -| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array | -| Output Paths | Invalid characters or format | Use valid filename/path format | +| Criterion | Common Fix | +|-----------|-----------| +| Valid Identifier | Convert to lowercase_underscores | +| Semantic Version | Set to `"1.0.0"` or fix format | +| Concise Summary | Shorten to <200 chars | +| Rich Description | Add multi-line explanation | +| Changelog Present | Add `changelog:` array | +| Complete Steps | Add missing required fields | +| Valid Dependencies | Fix step ID reference | +| Input Consistency | Add referenced step to dependencies | +| Output Paths | Use valid filename/path format | ### Step 5: Re-Run Review (If Needed) If any criteria failed: - -1. **Spawn a new sub-agent** with the updated job.yml content -2. **Review the new findings** -3. **Fix any remaining issues** -4. **Repeat until all 9 criteria pass** +1. Spawn a new sub-agent with updated job.yml +2. Review new findings +3. Fix remaining issues +4. Repeat until all 9 criteria pass ### Step 6: Confirm Completion When all 9 criteria pass: -1. **Announce success**: "All 9 doc spec quality criteria pass." -2. **List what was validated**: - - Valid Identifier - - Semantic Version - - Concise Summary - - Rich Description - - Changelog Present - - Complete Steps - - Valid Dependencies - - Input Consistency - - Output Paths -3. **Include the promise**: `Quality Criteria Met` -4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files." - -## Example Review Cycle - -``` -Claude: Let me review the job.yml against the doc spec quality criteria. - -[Spawns sub-agent with haiku model] - -Sub-agent response: -### Overall: 7/9 PASS - -### Criterion Results -1. Valid Identifier: PASS -2. Semantic Version: PASS -3. Concise Summary: FAIL - Issue: Summary is 245 characters, exceeds 200 char limit - Fix: Shorten to "Competitive analysis workflow for product positioning" -4. Rich Description: PASS -5. Changelog Present: FAIL - Issue: No changelog array present - Fix: Add changelog with initial version entry -6. Complete Steps: PASS -7. Valid Dependencies: PASS -8. Input Consistency: PASS -9. Output Paths: PASS - -### Summary of Required Fixes -1. Shorten summary to under 200 characters -2. Add changelog array with initial version - -Claude: I found 2 issues. Let me fix them. - -[Edits job.yml to shorten summary and add changelog] - -Claude: Let me verify the fixes with another review. - -[Spawns new sub-agent] - -Sub-agent response: -### Overall: 9/9 PASS - -### Summary of Required Fixes -No fixes required - all criteria pass - -Claude: All 9 doc spec quality criteria pass. - -Quality Criteria Met - -**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files. -``` - -## Quality Criteria - -- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review) -- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec -- **Findings Addressed**: All failed criteria were fixed by the main agent -- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed -- **Promise Included**: The response includes `Quality Criteria Met` when complete +1. Announce: "All 9 doc spec quality criteria pass." +2. Include: `Quality Criteria Met` +3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. ### Job Context diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md b/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md index 657e486e..ecbd239f 100644 --- a/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/job_yml_schema.md @@ -86,12 +86,39 @@ steps: quality_criteria: - "All competitors have descriptions" - "Sources are cited" - agent: general-purpose # delegate to agent type + agent: deepwork-jobs # delegate to expert (see Agent Delegation) hooks: after_agent: - script: hooks/validate.sh ``` +### Agent Delegation (The `agent` Field) + +The `agent` field specifies which expert should execute this step. When set: +1. The generated skill includes `context: fork` (runs in isolated context) +2. The generated skill includes `agent: [expert-name]` (loads that expert's knowledge) +3. The step runs with all the expert's topics, learnings, and domain knowledge available + +**This is how you make a step "run via" an expert.** + +```yaml +steps: + - id: define + name: "Define Job Specification" + description: "Creates a job.yml specification..." + instructions_file: steps/define.md + agent: deepwork-jobs # Runs with deepwork-jobs expert loaded + outputs: + - job.yml +``` + +Common agent values: +- `deepwork-jobs` - Expert for DeepWork job creation and management +- `deepwork-rules` - Expert for DeepWork rule creation +- Custom experts you've defined in `.deepwork/experts/` + +See the **Step Delegation** topic for detailed examples and patterns. + ## Output Formats Simple string: diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/step_delegation.md b/src/deepwork/standard/experts/deepwork_jobs/topics/step_delegation.md new file mode 100644 index 00000000..0efad748 --- /dev/null +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/step_delegation.md @@ -0,0 +1,145 @@ +--- +name: Step Delegation to Experts +keywords: + - agent + - expert + - delegation + - context fork + - sub-agent +last_updated: 2025-02-01 +--- + +# Step Delegation to Experts + +How to make job steps run via experts using the `agent` field. + +## The `agent` Field + +The `agent` field in a step definition specifies which expert should execute that step. This is the primary mechanism for making steps "run via" an expert. + +```yaml +steps: + - id: define + name: "Define Job Specification" + description: "Creates a job.yml specification..." + instructions_file: steps/define.md + agent: deepwork-jobs # <-- This step runs via the deepwork-jobs expert + outputs: + - job.yml +``` + +## What Happens When You Set `agent` + +When a step has `agent: expert-name`, the generated skill includes: + +1. **`context: fork`** - The step runs in an isolated context (sub-agent) +2. **`agent: expert-name`** - The expert's knowledge is loaded into that context + +The resulting skill frontmatter looks like: + +```yaml +--- +name: my_job.define +description: "Creates a job.yml specification..." +context: fork +agent: deepwork-jobs +--- +``` + +## How Expert Knowledge Flows + +When the skill runs: + +1. A forked context (sub-agent) is created +2. The expert file (e.g., `.claude/agents/dwe_deepwork-jobs.md`) is loaded +3. All expert topics, learnings, and domain knowledge become available +4. The step instructions execute with this enhanced context +5. The sub-agent completes and returns to the parent context + +## Real-World Example: deepwork_jobs + +The `deepwork_jobs` job itself uses expert delegation. All steps run via the `deepwork-jobs` expert: + +```yaml +steps: + - id: define + name: "Define Job Specification" + description: "Creates a job.yml specification..." + instructions_file: steps/define.md + agent: deepwork-jobs # Runs with job schema knowledge + outputs: + - file: job.yml + doc_spec: .deepwork/doc_specs/job_spec.md + + - id: review_job_spec + name: "Review Job Specification" + description: "Reviews job.yml against quality criteria..." + instructions_file: steps/review_job_spec.md + agent: deepwork-jobs # Same expert, different step + inputs: + - file: job.yml + from_step: define + outputs: + - file: job.yml + doc_spec: .deepwork/doc_specs/job_spec.md + + - id: implement + name: "Implement Job Steps" + description: "Generates step instruction files..." + instructions_file: steps/implement.md + agent: deepwork-jobs # Expert knowledge helps write good instructions + inputs: + - file: job.yml + from_step: review_job_spec + outputs: + - steps/ +``` + +## When to Use Expert Delegation + +Use `agent: expert-name` when: + +1. **Domain expertise is needed** - The step requires specialized knowledge that an expert provides +2. **Consistency across steps** - Multiple steps in a job should use the same expert context +3. **Complex validation** - The expert has knowledge about quality criteria or best practices +4. **Template awareness** - The expert knows about file formats, schemas, or conventions + +## Available Experts + +Standard experts that ship with DeepWork: + +- `deepwork-jobs` - Expert on job.yml schema, step instructions, skill generation +- `deepwork-rules` - Expert on rule creation and file-change triggers + +Custom experts can be created in `.deepwork/experts/` and referenced by name. + +## Expert vs. Sub-Agent Quality Review + +Note the difference between: + +1. **Expert delegation** (`agent: deepwork-jobs`) - The entire step runs with expert knowledge loaded +2. **Sub-agent quality review** (`quality_criteria` field) - A Haiku sub-agent validates outputs against criteria + +These can be combined - a step can run via an expert AND have quality criteria validated by a sub-agent: + +```yaml +steps: + - id: implement + instructions_file: steps/implement.md + agent: deepwork-jobs # Expert knowledge during execution + quality_criteria: # Sub-agent validates outputs + - "All instruction files are complete" + - "No placeholder content remains" +``` + +## Troubleshooting + +**Step not using expert knowledge?** +- Verify `agent: expert-name` is set in job.yml +- Run `deepwork sync` to regenerate skills +- Check the generated skill has `agent:` in its frontmatter + +**Expert not found?** +- Ensure the expert exists in `.deepwork/experts/[expert-name]/` +- Run `deepwork sync` to generate the expert agent file +- Check `.claude/agents/dwe_[expert-name].md` exists diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 4343cbda..3b14c068 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "1.0.0" +version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -22,32 +22,35 @@ workflows: - implement changelog: + - version: "1.1.0" + changes: "Simplified step instructions to leverage deepwork-jobs expert; cleaned up redundant content; improved clarity and conciseness" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - - version: "0.1.0" - changes: "Initial version" - - version: "0.2.0" - changes: "Replaced refine command with learn command for conversation-driven improvement" - - version: "0.3.0" - changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples" - - version: "0.4.0" - changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" - - version: "0.5.0" - changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions" - - version: "0.6.0" - changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation; learn.md now identifies and applies doc spec-related improvements" - - version: "0.7.0" - changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" - - version: "0.8.0" - changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" - version: "0.9.0" changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" + - version: "0.8.0" + changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" + - version: "0.7.0" + changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" + - version: "0.6.0" + changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation" + - version: "0.5.0" + changes: "Standardized on 'ask structured questions' phrasing for user input" + - version: "0.4.0" + changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" + - version: "0.3.0" + changes: "Added make_new_job.sh script and templates directory" + - version: "0.2.0" + changes: "Replaced refine command with learn command for conversation-driven improvement" + - version: "0.1.0" + changes: "Initial version" steps: - id: define name: "Define Job Specification" description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." instructions_file: steps/define.md + agent: deepwork-jobs inputs: - name: job_purpose description: "What complex task or workflow are you trying to accomplish?" @@ -59,6 +62,7 @@ steps: name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." instructions_file: steps/review_job_spec.md + agent: deepwork-jobs inputs: - file: job.yml from_step: define @@ -77,6 +81,7 @@ steps: name: "Implement Job Steps" description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." instructions_file: steps/implement.md + agent: deepwork-jobs inputs: - file: job.yml from_step: review_job_spec @@ -99,6 +104,7 @@ steps: name: "Learn from Job Execution" description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." instructions_file: steps/learn.md + agent: deepwork-jobs exposed: true inputs: - name: job_name diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 31de7440..237d2cd7 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -2,457 +2,114 @@ ## 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. +Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. ## Task Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. - -The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). +The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. ### Step 1: Understand the Job Purpose -Start by asking structured questions to understand what the user wants to accomplish: +Ask structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? - 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 1.5: Detect Document-Oriented Workflows +### Step 2: Detect Document-Oriented Workflows -**Check for document-focused patterns** in the user's description: -- Keywords: "report", "summary", "document", "create", "monthly", "quarterly", "for stakeholders", "for leadership" -- Final deliverable is a specific document (e.g., "AWS spending report", "competitive analysis", "sprint summary") +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly" +- Final deliverable is a specific document type - Recurring documents with consistent structure -**If a document-oriented workflow is detected:** - -1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first to ensure consistent quality." +**If detected**, inform the user and ask if they want to: +- Create a doc spec for consistent document quality +- Use an existing doc spec from `.deepwork/doc_specs/` +- Skip doc spec and proceed with simple outputs -2. Ask structured questions to understand if they want to: - - Create a doc spec for this document - - Use an existing doc spec (if any exist in `.deepwork/doc_specs/`) - - Skip doc spec and proceed with simple outputs +See the expert's documentation on doc specs for the full schema and examples. -### Step 1.6: Define the Doc Spec (if needed) +### Step 3: Define Each Step -When creating a doc spec, gather the following information: +For each major phase, gather: -1. **Document Identity** - - What is the document called? (e.g., "Monthly AWS Spending Report") - - Brief description of its purpose - - Where should these documents be stored? (path patterns like `finance/aws-reports/*.md`) +1. **Step Purpose**: What does this step accomplish? +2. **Inputs**: User parameters or files from previous steps +3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) +4. **Dependencies**: Which previous steps must complete first? +5. **Quality Criteria**: What makes a good vs. bad output? +6. **Agent Delegation**: Should this step run in a forked context? -2. **Audience and Context** - - Who reads this document? (target audience) - - How often is it produced? (frequency) +#### Work Product Storage Guidelines -3. **Quality Criteria** (3-5 criteria, each with name and description) - - **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve. +Job outputs belong in the main repository directory structure, not in dot-directories. - Examples for a spending report: - - **Visualization**: Must include charts showing spend breakdown by service - - **Variance Analysis**: Must compare current month against previous with percentages - - **Action Items**: Must include recommended cost optimization actions - - **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible. - -4. **Document Structure** - - What sections should it have? - - Any required elements (tables, charts, summaries)? - -### Step 1.7: Create the doc spec File (if needed) - -Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`: - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure. - -**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files). - -After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output. - -### Step 2: Define Each Step - -For each major phase they mentioned, ask structured questions to gather details: - -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? - - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output - - #### Work Product Storage Guidelines - - **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only. - - **Why this matters**: - - **Version control**: Work products in the main repo are tracked by git and visible in PRs - - **Discoverability**: Team members can find outputs without knowing about DeepWork internals - - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths - - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`) - - **Good output path patterns**: - ``` - competitive_research/competitors_list.md - competitive_research/acme_corp/research.md - operations/reports/2026-01/spending_analysis.md - docs/api/endpoints.md - ``` - - **Avoid these patterns**: - ``` - .deepwork/outputs/report.md # Hidden in dot-directory - output.md # Too generic, no context - research.md # Unclear which research - temp/draft.md # Transient-sounding paths - ``` - - **Organizing multi-file outputs**: - - Use the job name as a top-level folder when outputs are job-specific - - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/` - - Match existing project conventions when extending a codebase - - **When to include dates in paths**: - - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful. - ``` - operations/reports/2026-01/spending_analysis.md # Monthly report - keep history - hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf # Per-employee quarterly review - ``` - - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files. - ``` - competitive_research/acme_corp/swot.md # Current SWOT - updated over time - docs/architecture/overview.md # Living document - ``` - - **Supporting materials and intermediate outputs**: - - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output - - Name the dataroom folder by replacing the file extension with `_dataroom` - ``` - operations/reports/2026-01/spending_analysis.md # Final output - operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials - raw_data.csv - vendor_breakdown.md - notes.md - ``` - - This keeps supporting materials organized and discoverable without cluttering the main output location - -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? - -6. **Agent Delegation** (optional) - - Should this step be executed by a specific agent type? - - Use the `agent` field when the step should run in a forked context with a specific agent - - When `agent` is set, the generated skill automatically includes `context: fork` - - Available agent types: - - `general-purpose` - Standard agent for multi-step tasks - - ```yaml - steps: - - id: research_step - agent: general-purpose # Delegates to the general-purpose agent - ``` - -**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. - -#### Doc Spec-Aware Output Format - -When a step produces a document with a doc spec reference, use this format in job.yml: - -```yaml -outputs: - - file: reports/monthly_spending.md - doc_spec: .deepwork/doc_specs/monthly_aws_report.md +**Good patterns**: ``` - -The doc spec's quality criteria will automatically be included in the generated skill, ensuring consistent document quality. - -### Capability Considerations - -When defining steps, identify any that require specialized tools: - -**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. - -### Step 3: Validate the Workflow - -After gathering information about all steps: - -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: Define Quality Validation (Stop Hooks) - -For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. - -**Ask structured questions about quality validation:** -- "Are there specific quality criteria that must be met for this step?" -- "Would you like the agent to validate its work before completing?" -- "What would make you send the work back for revision?" - -**Stop hooks are particularly valuable for:** -- Steps with complex outputs that need multiple checks -- Steps where quality is critical (final deliverables) -- Steps with subjective quality criteria that benefit from AI self-review - -**Three types of stop hooks are supported:** - -1. **Inline Prompt** (`prompt`) - Best for simple quality criteria - ```yaml - stop_hooks: - - prompt: | - Verify the output meets these criteria: - 1. Contains at least 5 competitors - 2. Each competitor has a description - 3. Selection rationale is clear - ``` - -2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - -3. **Script** (`script`) - For programmatic validation (tests, linting) - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -**Multiple hooks can be combined:** -```yaml -stop_hooks: - - script: hooks/lint_output.sh - - prompt: "Verify the content is comprehensive and well-organized" +competitive_research/competitors_list.md +operations/reports/2026-01/spending_analysis.md ``` -**Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). - -### Step 5: Create the Job Directory and Specification - -Only after you have complete understanding, create the job directory and `job.yml` file: - -**First, create the directory structure** using the `make_new_job.sh` script: - -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +**Avoid**: ``` - -This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory -- `.deepwork/jobs/[job_name]/steps/` - For step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts -- `.deepwork/jobs/[job_name]/templates/` - For example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance - -**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) - -**Doc Spec**: See `.deepwork/doc_specs/job_spec.md` for the complete specification with quality criteria. - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. - -**Important**: -- Use lowercase with underscores for job name and step IDs -- Ensure file inputs reference steps in dependencies -- 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 -- Include a `changelog` section with an initial entry for version 1.0.0 - -## Example Dialog - +.deepwork/outputs/report.md # Hidden in dot-directory +output.md # Too generic ``` -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? +**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. -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 in the project root, or in a subdirectory like `research/` or `data/`? - -User: Just call it `competitors_list.md` in the project root. - -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! +**Supporting materials**: Place in `_dataroom` folder as peer to final output: +``` +operations/reports/2026-01/spending_analysis.md +operations/reports/2026-01/spending_analysis_dataroom/ + raw_data.csv + notes.md +``` -Claude: Great! Creating the job.yml specification now... +### Step 4: Validate the Workflow -[Creates .deepwork/jobs/competitive_research/job.yml with the complete spec] +After gathering all information: -✓ Job specification created! +1. **Review the flow** - Summarize and show how outputs feed into the next step +2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies +3. **Confirm details** - Job name, summary (max 200 chars), description, version -**File created:** -- .deepwork/jobs/competitive_research/job.yml +### Step 5: Create the Job Specification -**Next step:** -Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria. +**First, create the directory structure**: +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` -## Important Guidelines - -1. **Focus on specification only** - Don't create instruction files yet -2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool -3. **Rich context in description** - This helps with future refinement -4. **Validate understanding** - Summarize and confirm before creating -5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed +**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` -## 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 +Refer to the expert for the complete job.yml schema. Key validation rules: +- Job name: lowercase, underscores only, no spaces +- Version: semantic versioning (start with 1.0.0) +- Summary: max 200 characters - 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 +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example -The complete YAML specification file (example shown in Step 5 above). +## Output -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the new job being created) +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. After creating the file: 1. Inform the user that the specification is complete -2. Recommend that they review the job.yml file +2. Recommend they review the job.yml file 3. Tell them to run `/deepwork_jobs.review_job_spec` next - diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index 749c8c6f..bc1fa3d8 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -2,232 +2,105 @@ ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. +Read the `job.yml` specification and create all necessary files to make the job functional. -### Step 1: Create Directory Structure Using Script - -Run the `make_new_job.sh` script to create the standard directory structure: +### Step 1: Create Directory Structure +Run the setup script: ```bash .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory - `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) -- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: -```bash -mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates -touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep -``` +**Note**: If directory already exists from define step, create missing subdirectories manually. ### Step 2: Read and Validate the Specification -1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec 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 +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate structure (name, version, summary, description, steps) +3. Check dependencies are valid and non-circular +4. Extract step details for instruction generation ### 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`. +Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. +**Templates**: +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure +- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. +**Guidelines**: -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- `job.yml.example` - Complete job specification example -- `step_instruction.md.example` - Complete step instruction example - -**Guidelines for generating instructions:** - -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 +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to each 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 -6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks -7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" - -### Handling Stop Hooks - -If a step in the job.yml has `stop_hooks` defined, the generated instruction file should: - -1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the stop hooks will validate -2. **Be explicit about success** - Help the agent understand when the step is truly complete -3. **Include the promise pattern** - Mention that `✓ Quality Criteria Met` should be included when criteria are met - -**Example: If the job.yml has:** -```yaml -- id: research_competitors - name: "Research Competitors" - stop_hooks: - - prompt: | - Verify the research meets criteria: - 1. Each competitor has at least 3 data points - 2. Sources are cited - 3. Information is current (within last year) -``` - -**The instruction file should include:** -```markdown -## Quality Criteria +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - When a step has user inputs, MUST use this phrase +6. **Align with hooks** - If step has `hooks` defined, match quality criteria -- Each competitor has at least 3 distinct data points -- All information is sourced with citations -- Data is current (from within the last year) -- When all criteria are met, include `✓ Quality Criteria Met` in your response -``` - -This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. - -### Using Supplementary Reference Files +**Handling Hooks**: -Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. - -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. +If a step has hooks defined, the instruction file should: +- Mirror the quality criteria that hooks will validate +- Be explicit about what success looks like +- Mention the `Quality Criteria Met` pattern when criteria are met ### Step 4: Verify job.yml Location -Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it. +Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. ### Step 5: Sync Skills -Run `deepwork sync` to generate the skills for this job: - +Run: ```bash deepwork sync ``` -This will: -- Parse the job definition -- Generate skills for each step -- Make the skills available in `.claude/skills/` (or appropriate platform directory) +This generates skills for each step in `.claude/skills/` (or platform-specific directory). -### Step 6: Consider Rules for the New Job +### Step 6: Consider Rules -After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain. +After implementing, consider whether **rules** would help enforce quality. **What are rules?** +Automated guardrails in `.deepwork/rules/` that trigger when files change. -Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure: -- Documentation stays in sync with code -- Team guidelines are followed -- Architectural decisions are respected -- Quality standards are maintained - -**When to suggest rules:** - -Think about the job you just implemented and ask: -- Does this job produce outputs that other files depend on? -- Are there documentation files that should be updated when this job's outputs change? -- Are there quality checks or reviews that should happen when certain files in this domain change? -- Could changes to the job's output files impact other parts of the project? - -**Examples of rules that might make sense:** +**When to suggest rules**: +- Job produces outputs that other files depend on +- Documentation should stay in sync with outputs +- Quality checks should happen when certain files change +**Examples**: | Job Type | Potential Rule | |----------|----------------| -| API Design | "Update API docs when endpoint definitions change" | -| Database Schema | "Review migrations when schema files change" | -| Competitive Research | "Update strategy docs when competitor analysis changes" | -| Feature Development | "Update changelog when feature files change" | -| Configuration Management | "Update install guide when config files change" | - -**How to offer rule creation:** +| API Design | Update docs when endpoints change | +| Database Schema | Review migrations when schema changes | +| Competitive Research | Update strategy when analysis changes | -If you identify one or more rules that would benefit the user, explain: -1. **What the rule would do** - What triggers it and what action it prompts -2. **Why it would help** - How it prevents common mistakes or keeps things in sync -3. **What files it would watch** - The trigger patterns - -Then ask the user: - -> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up." - -If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule. - -**Example dialogue:** - -``` -Based on the competitive_research job you just created, I noticed that when -competitor analysis files change, it would be helpful to remind you to update -your strategy documentation. - -I'd suggest a rule like: -- **Name**: "Update strategy when competitor analysis changes" -- **Trigger**: `**/positioning_report.md` -- **Action**: Prompt to review and update `docs/strategy.md` - -Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up. -``` - -**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense. - -## Example Implementation - -For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - -## Important Guidelines - -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) -- No file system errors +If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. ## 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 +Before marking complete: +- [ ] job.yml validated and in place +- [ ] All step instruction files created (complete, not stubs) +- [ ] Instructions are specific and actionable +- [ ] Output examples provided +- [ ] Quality criteria defined for each step +- [ ] User input steps use "ask structured questions" - [ ] `deepwork sync` executed successfully -- [ ] Skills generated in platform directory -- [ ] Considered whether rules would benefit this job (Step 6) -- [ ] If rules suggested, offered to run `/deepwork_rules.define` - -## 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 -- Steps with user inputs explicitly use "ask structured questions" phrasing -- Sync completed successfully -- Skills available for use -- Thoughtfully considered relevant rules for the job domain +- [ ] Skills available in platform directory +- [ ] Considered relevant rules for job domain + +## Output + +Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index bfb393a5..bae38c0e 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -2,354 +2,137 @@ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. ## Task -Analyze the conversation history to extract learnings and improvements, then apply them appropriately: -- **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic +Analyze the conversation history to extract learnings and apply them appropriately: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md ### Step 1: Analyze Conversation for Job Executions -1. **Scan the conversation** for DeepWork slash commands that were run - - Look for patterns like `/job_name.step_id` - - Identify which jobs and steps were executed - - Note the order of execution +1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns +2. **Identify the target folder** - Deepest common folder for future work on this topic +3. **If no job specified**, ask the user which job to analyze -2. **Identify the target folder** - - This should be the deepest common folder that would contain all work on the topic in the future - - Should be clear from conversation history where work was done - - If unclear, run `git diff` to see where changes were made on the branch - -3. **If no job was specified**, ask the user: - - "Which DeepWork job would you like me to learn from?" - - List available jobs from `.deepwork/jobs/` - -### Step 2: Identify Points of Confusion and Inefficiency +### Step 2: Identify Issues Review the conversation for: -1. **Confusion signals** - - Questions the agent asked that shouldn't have been necessary - - Misunderstandings about what a step required - - Incorrect outputs that needed correction - - Ambiguous instructions that led to wrong interpretations +**Confusion signals**: +- Unnecessary questions from the agent +- Misunderstandings about step requirements +- Incorrect outputs needing correction -2. **Inefficiency signals** - - Extra steps or iterations that were needed - - Information that had to be repeated - - Context that was missing from instructions - - Dependencies that weren't clear +**Inefficiency signals**: +- Extra iterations needed +- Information repeated multiple times +- Missing context or dependencies -3. **Error patterns** - - Failed validations and why they failed - - Quality criteria that were misunderstood - - Edge cases that weren't handled +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -4. **Success patterns** - - What worked particularly well - - Efficient approaches worth preserving - - Good examples that could be added to instructions +**Success patterns**: +- What worked well +- Efficient approaches to preserve ### Step 3: Classify Learnings -For each learning identified, determine if it is: - -**Generalizable** (should improve instructions): +**Generalizable** (update instructions): - Would help ANY future run of this job - Addresses unclear or missing guidance -- Fixes incorrect assumptions in instructions -- Adds helpful examples or context -- Examples: - - "Step instructions should mention that X format is required" - - "Quality criteria should include checking for Y" - - "Add example of correct output format" - -**doc spec-Related** (should improve doc spec files): +- Adds helpful examples + +**Doc spec-related** (update doc spec files): - Improvements to document quality criteria -- Changes to document structure or format -- Updated audience or frequency information -- Examples: - - "The report should include a summary table" - - "Quality criterion 'Visualization' needs clearer requirements" - - "Documents need a section for action items" - -**Bespoke** (should go in AGENTS.md): +- Changes to document structure +- Updated audience or format info + +**Bespoke** (add to AGENTS.md): - Specific to THIS project/codebase/run -- Depends on local conventions or structure - References specific files or paths -- Would not apply to other uses of this job -- Examples: - - "In this codebase, API endpoints are in `src/api/`" - - "This project uses camelCase for function names" - - "The main config file is at `config/settings.yml`" - -### Step 3.5: Identify doc spec-Related Learnings - -Review the conversation for doc spec-related improvements: - -1. **Quality Criteria Changes** - - Were any quality criteria unclear or insufficient? - - Did the agent repeatedly fail certain criteria? - - Are there new criteria that should be added? - -2. **Document Structure Changes** - - Did the user request different sections? - - Were parts of the document format confusing? - - Should the example document be updated? - -3. **Metadata Updates** - - Has the target audience changed? - - Should frequency or path patterns be updated? - -**Signals for doc spec improvements:** -- User asked for changes to document format -- Repeated validation failures on specific criteria -- Feedback about missing sections or information -- Changes to how documents are organized/stored - -### Step 4: Update Job Instructions (Generalizable Learnings) - -For each generalizable learning: - -1. **Locate the instruction file** - - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements** - - Add missing context or clarification - - Include helpful examples - - Clarify ambiguous instructions - - Update quality criteria if needed - -3. **Keep instructions concise** - - Avoid redundancy - don't repeat the same guidance in multiple places - - Be direct - remove verbose explanations that don't add value - - Prefer bullet points over paragraphs where appropriate - -4. **Preserve instruction structure** - - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - - Add to appropriate sections rather than restructuring - - Maintain consistency with other steps - -5. **Track changes for changelog** - - Note what was changed and why - - Prepare changelog entry for job.yml +- Local conventions -### Step 4b: Extract Shared Content into Referenced Files +### Step 4: Update Job Instructions -Review all instruction files for the job and identify content that: -- Appears in multiple step instructions (duplicated) -- Is lengthy and could be extracted for clarity -- Would benefit from being maintained in one place +For generalizable learnings: -**Extract to shared files:** +1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements - add context, examples, clarify ambiguity +3. Keep instructions concise - no redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) +5. Note changes for changelog -1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` - - `conventions.md` - Coding/formatting conventions used across steps - - `examples.md` - Common examples referenced by multiple steps - - `schemas.md` - Data structures or formats used throughout +**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. -2. **Reference from instructions** using markdown includes or explicit references: - ```markdown - ## Conventions +### Step 5: Update Doc Spec Files (If Applicable) - Follow the conventions defined in `shared/conventions.md`. - ``` - -3. **Benefits of extraction:** - - Single source of truth - update once, applies everywhere - - Shorter instruction files - easier to read and maintain - - Consistent guidance across steps - -### Step 4.5: Update doc spec Files (doc spec-Related Learnings) - -If doc spec-related learnings were identified: - -1. **Locate the doc spec file** - - Find doc spec references in job.yml outputs (look for `doc_spec: .deepwork/doc_specs/[doc_spec_name].md`) - - doc spec files are at `.deepwork/doc_specs/[doc_spec_name].md` +If doc spec learnings were identified: -2. **Update quality_criteria array** - - Add new criteria with name and description - - Modify existing criteria descriptions for clarity - - Remove criteria that are no longer relevant +1. Find doc spec references in job.yml outputs +2. Update quality criteria with clearer requirements +3. Update example document if structure changed +4. Update metadata (audience, frequency, paths) -3. **Update example document** - - Modify the markdown body to reflect structure changes - - Ensure the example matches updated criteria +### Step 6: Create/Update AGENTS.md -4. **Update metadata as needed** - - target_audience: If audience has changed - - frequency: If production cadence has changed - - path_patterns: If storage location has changed +For bespoke learnings: -**Example doc spec update:** -```yaml -# Before -quality_criteria: - - name: Visualization - description: Include charts +1. **Determine location** - Deepest common folder for the topic +2. **Use file references** - Link to source files rather than duplicating content +3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` -# After -quality_criteria: - - name: Visualization - description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend +**Good patterns** (references): +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` ``` -### Step 5: Create/Update AGENTS.md (Bespoke Learnings) - -The AGENTS.md file captures project-specific knowledge that helps future agent runs. - -1. **Determine the correct location** - - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - - This ensures the knowledge is available when working in that context - - If uncertain, place at the project root - -2. **Use file references where possible** - - Instead of duplicating information, reference source files - - This keeps AGENTS.md in sync as the codebase evolves - - Pattern: "See `path/to/file.ext` for [description]" - -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. - -4. **Writing entries** - - Be concise but specific - - Always prefer file references over inline content - - Use line numbers when referencing specific code: `file.ext:42` - - Group related learnings together +**Avoid** (duplicating): +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +``` -### Step 6: Update Job Version and Changelog +### Step 7: Update Job Version and Changelog If instruction files were modified: -1. **Bump version in job.yml** - - Patch version (0.0.x) for instruction improvements - - Minor version (0.x.0) if quality criteria changed - -2. **Add changelog entry** +1. Bump version (patch for improvements, minor for criteria changes) +2. Add changelog entry: ```yaml - version: "[new_version]" - changes: "Improved [step] instructions based on execution learnings: [brief description]" + changes: "Improved [step] based on execution learnings: [brief description]" ``` -### Step 7: Sync Skills +### Step 8: Sync Skills -**Run deepwork sync** (if instructions were modified) +If instructions were modified: ```bash deepwork sync ``` -## File Reference Patterns - -When adding entries to AGENTS.md, prefer these patterns: - -**Good (references)**: -```markdown -- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` -- Configuration schema: Defined in `config/schema.json` -``` - -**Avoid (duplicating)**: -```markdown -- API endpoints should return JSON with this format: { status: ..., data: ... } -- Error handling should use try/catch with custom error classes -- Configuration requires these fields: name, version, ... -``` - ## Quality Criteria -- Conversation has been analyzed for job executions -- Points of confusion and inefficiency are identified -- Learnings are correctly classified (generalizable vs bespoke) -- Job instructions updated for generalizable improvements -- Instructions are concise - no redundancy or unnecessary verbosity -- Shared/lengthy content extracted into referenced files where appropriate -- AGENTS.md created/updated with bespoke learnings -- File references used instead of duplicating content -- AGENTS.md is in the correct folder (the deepest common folder for the topic) -- When all criteria are met, include `✓ Quality Criteria Met` - -## Example Dialog - -``` -User: /deepwork_jobs.learn - -Claude: I'll analyze this conversation for learnings from DeepWork job executions. - -**Conversation Analysis** - -I found the following job executions: -1. `/competitive_research.identify_competitors` - Completed -2. `/competitive_research.research_competitors` - Completed with 2 iterations -3. `/competitive_research.comparative_analysis` - Completed - -**Identified Issues** - -1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. - -2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. - -**Classification** - -- Generalizable: Add pricing to research requirements in instructions -- Bespoke: This project focuses on B2B SaaS in the HR tech space - -**Actions Taken** - -1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: - - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements - - Added note about carrying forward industry context from previous step - -2. Created `./competitive_research_output/AGENTS.md`: - ```markdown - # Project Context for Competitive Research - - ## Job-Specific Context - - ### competitive_research - - #### Industry Focus - - Domain: B2B SaaS, HR Technology sector - - See `identify_competitors_output.md` for market definition - - #### Competitors Identified - - Reference: `competitor_list.md` for full details - - ## Last Updated - - Date: 2024-01-15 - - From conversation about: Initial competitive analysis run - ``` - -3. Updated job.yml version to 1.0.1 with changelog entry - -4. Ran `deepwork sync` - -**Summary** - -Updated job instructions and created AGENTS.md with bespoke learnings. -``` +- Conversation analyzed for job executions +- Learnings correctly classified (generalizable vs bespoke) +- Instructions updated for generalizable improvements +- Instructions remain concise +- Shared content extracted where appropriate +- AGENTS.md in correct folder with file references +- Sync complete if instructions modified +- When complete: `Quality Criteria Met` -## Handling Edge Cases +## Edge Cases -**No job executions found**: -- Ask user which job they'd like to analyze -- Or offer to review available jobs +**No job executions found**: Ask user which job to analyze -**Multiple jobs executed**: -- Analyze each job separately -- Create separate AGENTS.md entries or files as appropriate +**Multiple jobs executed**: Analyze each separately -**AGENTS.md already exists**: -- Read existing content -- Append new learnings to appropriate sections -- Update "Last Updated" section +**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" -**No issues found**: -- Document what worked well -- Consider if any successful patterns should be added to instructions as examples +**No issues found**: Document what worked well, consider adding as examples -**Sensitive information**: -- Never include secrets, credentials, or PII in AGENTS.md -- Reference config files instead of including values +**Sensitive information**: Never include secrets or PII - reference config files instead diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md index fcc0ae9c..87a2d7a9 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md @@ -2,207 +2,105 @@ ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass. +Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. ### Step 1: Read the Job Specification -Read the `job.yml` file created in the define step: - -``` -.deepwork/jobs/[job_name]/job.yml -``` - -Also read the doc spec for reference: - -``` -.deepwork/doc_specs/job_spec.md -``` +Read both files: +- `.deepwork/jobs/[job_name]/job.yml` - The specification to review +- `.deepwork/doc_specs/job_spec.md` - The quality criteria ### Step 2: Spawn Review Sub-Agent -Use the Task tool to spawn a sub-agent that will provide an unbiased review: +Use the Task tool with: +- `subagent_type`: "general-purpose" +- `model`: "haiku" +- `description`: "Review job.yml against doc spec" -``` -Task tool parameters: -- subagent_type: "general-purpose" -- model: "haiku" -- description: "Review job.yml against doc spec" -- prompt: [see below] -``` - -**Sub-agent prompt template:** +**Sub-agent prompt**: ``` -Review this job.yml against the following 9 quality criteria from the doc spec. +Review this job.yml against the following 9 quality criteria. -For each criterion, respond with: -- PASS or FAIL -- If FAIL: specific issue and suggested fix +For each criterion, respond with PASS or FAIL. +If FAIL: provide the specific issue and suggested fix. ## job.yml Content -[paste the full job.yml content here] +[paste full job.yml content] ## Quality Criteria -1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`) - -2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`) - -3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes - -4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users - -5. **Changelog Present**: Must include a changelog array with at least the initial version entry - -6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array - -7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references - -8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array - -9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`) +1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) +2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) +3. **Concise Summary**: Under 200 characters, describes what job accomplishes +4. **Rich Description**: Multi-line explaining problem, process, outcomes, users +5. **Changelog Present**: Array with at least initial version entry +6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: Reference existing step IDs, no circular references +8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies +9. **Output Paths**: Valid filenames or paths ## Response Format -Respond with a structured evaluation: - ### Overall: [X/9 PASS] ### Criterion Results - 1. Valid Identifier: [PASS/FAIL] [If FAIL: Issue and fix] - -2. Semantic Version: [PASS/FAIL] - [If FAIL: Issue and fix] - -[... continue for all 9 criteria ...] +... ### Summary of Required Fixes - -[List any fixes needed, or "No fixes required - all criteria pass"] +[List fixes needed, or "No fixes required"] ``` -### Step 3: Review Sub-Agent Findings +### Step 3: Review Findings Parse the sub-agent's response: - -1. **Count passing criteria** - How many of the 9 criteria passed? -2. **Identify failures** - List specific criteria that failed -3. **Note suggested fixes** - What changes does the sub-agent recommend? +1. Count passing criteria +2. Identify failures +3. Note suggested fixes ### Step 4: Fix Failed Criteria -For each failed criterion, edit the job.yml to address the issue: +Edit job.yml to address each failure: -**Common fixes by criterion:** - -| Criterion | Common Issue | Fix | -|-----------|-------------|-----| -| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | -| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format | -| Concise Summary | Too long or vague | Shorten to <200 chars, be specific | -| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users | -| Changelog Present | Missing changelog | Add `changelog:` with initial version entry | -| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies | -| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies | -| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array | -| Output Paths | Invalid characters or format | Use valid filename/path format | +| Criterion | Common Fix | +|-----------|-----------| +| Valid Identifier | Convert to lowercase_underscores | +| Semantic Version | Set to `"1.0.0"` or fix format | +| Concise Summary | Shorten to <200 chars | +| Rich Description | Add multi-line explanation | +| Changelog Present | Add `changelog:` array | +| Complete Steps | Add missing required fields | +| Valid Dependencies | Fix step ID reference | +| Input Consistency | Add referenced step to dependencies | +| Output Paths | Use valid filename/path format | ### Step 5: Re-Run Review (If Needed) If any criteria failed: - -1. **Spawn a new sub-agent** with the updated job.yml content -2. **Review the new findings** -3. **Fix any remaining issues** -4. **Repeat until all 9 criteria pass** +1. Spawn a new sub-agent with updated job.yml +2. Review new findings +3. Fix remaining issues +4. Repeat until all 9 criteria pass ### Step 6: Confirm Completion When all 9 criteria pass: -1. **Announce success**: "All 9 doc spec quality criteria pass." -2. **List what was validated**: - - Valid Identifier - - Semantic Version - - Concise Summary - - Rich Description - - Changelog Present - - Complete Steps - - Valid Dependencies - - Input Consistency - - Output Paths -3. **Include the promise**: `Quality Criteria Met` -4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files." - -## Example Review Cycle - -``` -Claude: Let me review the job.yml against the doc spec quality criteria. - -[Spawns sub-agent with haiku model] - -Sub-agent response: -### Overall: 7/9 PASS - -### Criterion Results -1. Valid Identifier: PASS -2. Semantic Version: PASS -3. Concise Summary: FAIL - Issue: Summary is 245 characters, exceeds 200 char limit - Fix: Shorten to "Competitive analysis workflow for product positioning" -4. Rich Description: PASS -5. Changelog Present: FAIL - Issue: No changelog array present - Fix: Add changelog with initial version entry -6. Complete Steps: PASS -7. Valid Dependencies: PASS -8. Input Consistency: PASS -9. Output Paths: PASS - -### Summary of Required Fixes -1. Shorten summary to under 200 characters -2. Add changelog array with initial version - -Claude: I found 2 issues. Let me fix them. - -[Edits job.yml to shorten summary and add changelog] - -Claude: Let me verify the fixes with another review. - -[Spawns new sub-agent] - -Sub-agent response: -### Overall: 9/9 PASS - -### Summary of Required Fixes -No fixes required - all criteria pass - -Claude: All 9 doc spec quality criteria pass. - -Quality Criteria Met - -**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files. -``` - -## Quality Criteria - -- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review) -- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec -- **Findings Addressed**: All failed criteria were fixed by the main agent -- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed -- **Promise Included**: The response includes `Quality Criteria Met` when complete +1. Announce: "All 9 doc spec quality criteria pass." +2. Include: `Quality Criteria Met` +3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. From 0f333884941583b712d4c0ef94dce97cb57fd3e0 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 1 Feb 2026 10:00:45 -0700 Subject: [PATCH 7/9] deepwork_job reworked with the expert --- .claude/skills/deepwork_jobs.define/SKILL.md | 129 ++++--------- .../skills/deepwork_jobs.implement/SKILL.md | 140 ++++---------- .claude/skills/deepwork_jobs.learn/SKILL.md | 175 ++++-------------- .../deepwork_jobs.review_job_spec/SKILL.md | 133 ++++--------- .deepwork/jobs/deepwork_jobs/job.yml | 65 ++----- .deepwork/jobs/deepwork_jobs/steps/define.md | 129 ++++--------- .../jobs/deepwork_jobs/steps/implement.md | 117 ++++-------- .deepwork/jobs/deepwork_jobs/steps/learn.md | 149 ++++----------- .../deepwork_jobs/steps/review_job_spec.md | 115 ++++-------- .gemini/skills/deepwork_jobs/define.toml | 129 ++++--------- .gemini/skills/deepwork_jobs/implement.toml | 131 ++++--------- .gemini/skills/deepwork_jobs/learn.toml | 166 ++++------------- .../skills/deepwork_jobs/review_job_spec.toml | 124 ++++--------- .../standard_jobs/deepwork_jobs/job.yml | 65 ++----- .../deepwork_jobs/steps/define.md | 129 ++++--------- .../deepwork_jobs/steps/implement.md | 117 ++++-------- .../deepwork_jobs/steps/learn.md | 149 ++++----------- .../deepwork_jobs/steps/review_job_spec.md | 115 ++++-------- 18 files changed, 600 insertions(+), 1677 deletions(-) diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index 9026396c..83d1bea8 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -24,117 +24,54 @@ agent: deepwork-jobs ## Objective -Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. +Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. ## Task -Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. +### Process -### Step 1: Understand the Job Purpose +1. **Understand the job purpose** + - Ask structured questions about the overall goal, domain, and frequency + - Understand what success looks like and who the audience is + - Identify the major phases of the workflow -Ask structured questions to understand what the user wants to accomplish: +2. **Detect document-oriented workflows** + - Look for patterns: "report", "summary", "monthly", "for stakeholders" + - If detected, offer to create a doc spec for consistent quality + - Use `.deepwork/doc_specs/job_spec.md` as a reference example -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) +3. **Define each step** + - For each phase, gather: purpose, inputs, outputs, dependencies + - Ask about output file paths and organization + - Consider whether steps need agent delegation -2. **What does success look like?** - - What's the final deliverable or outcome? - - Who is the audience for the output? +4. **Validate the workflow** + - Summarize the complete workflow + - Check for gaps in inputs/outputs between steps + - Confirm job name, summary, and version -3. **What are the major phases?** - - What are the distinct stages from start to finish? - - Are there any dependencies between phases? +5. **Create the job specification** + - Run `make_new_job.sh` to create directory structure: + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` + - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` -### Step 2: Detect Document-Oriented Workflows +### Key Guidelines -Check for document-focused patterns in the user's description: -- Keywords: "report", "summary", "document", "monthly", "quarterly" -- Final deliverable is a specific document type -- Recurring documents with consistent structure - -**If detected**, inform the user and ask if they want to: -- Create a doc spec for consistent document quality -- Use an existing doc spec from `.deepwork/doc_specs/` -- Skip doc spec and proceed with simple outputs - -See the expert's documentation on doc specs for the full schema and examples. - -### Step 3: Define Each Step - -For each major phase, gather: - -1. **Step Purpose**: What does this step accomplish? -2. **Inputs**: User parameters or files from previous steps -3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) -4. **Dependencies**: Which previous steps must complete first? -5. **Quality Criteria**: What makes a good vs. bad output? -6. **Agent Delegation**: Should this step run in a forked context? - -#### Work Product Storage Guidelines - -Job outputs belong in the main repository directory structure, not in dot-directories. - -**Good patterns**: -``` -competitive_research/competitors_list.md -operations/reports/2026-01/spending_analysis.md -``` - -**Avoid**: -``` -.deepwork/outputs/report.md # Hidden in dot-directory -output.md # Too generic -``` - -**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. - -**Supporting materials**: Place in `_dataroom` folder as peer to final output: -``` -operations/reports/2026-01/spending_analysis.md -operations/reports/2026-01/spending_analysis_dataroom/ - raw_data.csv - notes.md -``` - -### Step 4: Validate the Workflow - -After gathering all information: - -1. **Review the flow** - Summarize and show how outputs feed into the next step -2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies -3. **Confirm details** - Job name, summary (max 200 chars), description, version - -### Step 5: Create the Job Specification - -**First, create the directory structure**: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` - -**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` - -Refer to the expert for the complete job.yml schema. Key validation rules: -- Job name: lowercase, underscores only, no spaces -- Version: semantic versioning (start with 1.0.0) -- Summary: max 200 characters -- File inputs: `from_step` must be in dependencies -- At least one output per step - -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example +- **Ask structured questions** using the AskUserQuestion tool +- **Work products go in main repo**, not `.deepwork/` (for discoverability) +- **Use dates in paths** for periodic outputs that accumulate +- **Use `_dataroom` folders** for supporting materials +- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. +Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. -After creating the file: -1. Inform the user that the specification is complete -2. Recommend they review the job.yml file -3. Tell them to run `/deepwork_jobs.review_job_spec` next +After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. ### Job Context diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index 03ff85d7..009939a9 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -28,108 +28,65 @@ Before proceeding, confirm these steps are complete: ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. +Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. ## Task -Read the `job.yml` specification and create all necessary files to make the job functional. +Read the job.yml and create comprehensive instruction files for each step. -### Step 1: Create Directory Structure +### Process -Run the setup script: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` +1. **Create directory structure** (if needed) + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` -This creates: -- `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts -- `.deepwork/jobs/[job_name]/templates/` - Example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance +2. **Read and validate the specification** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Extract job name, description, and step details + - Understand the workflow structure -**Note**: If directory already exists from define step, create missing subdirectories manually. +3. **Generate step instruction files** + - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step + - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference + - Each file must include: Objective, Task, Process, Output Format, Quality Criteria -### Step 2: Read and Validate the Specification +4. **Sync skills** + ```bash + deepwork sync + ``` -1. Read `.deepwork/jobs/[job_name]/job.yml` -2. Validate structure (name, version, summary, description, steps) -3. Check dependencies are valid and non-circular -4. Extract step details for instruction generation +5. **Consider rules for the new job** + - Think about whether rules would help maintain quality + - If relevant, explain and offer to run `/deepwork_rules.define` -### Step 3: Generate Step Instruction Files +### Instruction File Guidelines -Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. +- **Be specific** - tailor to each step's purpose, not generic advice +- **Provide examples** - show what good output looks like +- **Include quality criteria** - how to verify the step is complete +- **Use "ask structured questions"** - for steps that gather user input +- **Align with hooks** - if step has hooks, match the validation criteria -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example +### Templates Available -**Guidelines**: - -1. **Use the job description** - It provides crucial context -2. **Be specific** - Tailor instructions to each step's purpose -3. **Provide examples** - Show what good output looks like -4. **Explain the "why"** - Help understand the step's role in the workflow -5. **Ask structured questions** - When a step has user inputs, MUST use this phrase -6. **Align with hooks** - If step has `hooks` defined, match quality criteria - -**Handling Hooks**: - -If a step has hooks defined, the instruction file should: -- Mirror the quality criteria that hooks will validate -- Be explicit about what success looks like -- Mention the `Quality Criteria Met` pattern when criteria are met - -### Step 4: Verify job.yml Location - -Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. - -### Step 5: Sync Skills - -Run: -```bash -deepwork sync -``` - -This generates skills for each step in `.claude/skills/` (or platform-specific directory). - -### Step 6: Consider Rules - -After implementing, consider whether **rules** would help enforce quality. - -**What are rules?** -Automated guardrails in `.deepwork/rules/` that trigger when files change. - -**When to suggest rules**: -- Job produces outputs that other files depend on -- Documentation should stay in sync with outputs -- Quality checks should happen when certain files change - -**Examples**: -| Job Type | Potential Rule | -|----------|----------------| -| API Design | Update docs when endpoints change | -| Database Schema | Review migrations when schema changes | -| Competitive Research | Update strategy when analysis changes | - -If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- Examples: `job.yml.example`, `step_instruction.md.example` ## Completion Checklist -Before marking complete: -- [ ] job.yml validated and in place -- [ ] All step instruction files created (complete, not stubs) +- [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined for each step -- [ ] User input steps use "ask structured questions" +- [ ] Quality criteria defined - [ ] `deepwork sync` executed successfully -- [ ] Skills available in platform directory -- [ ] Considered relevant rules for job domain +- [ ] Rules considered (suggest if genuinely helpful) ## Output -Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. +Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. ### Job Context @@ -171,29 +128,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - Do NOT proceed without required inputs; ask the user if any are missing - Do NOT modify files outside the scope of this step's defined outputs -## Quality Validation - -**Before completing this step, you MUST have your work reviewed against the quality criteria below.** - -Use a sub-agent (Haiku model) to review your work against these criteria: - -**Criteria (all must be satisfied)**: -1. **Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly? -2. **Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)? -3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic? -4. **Output Examples**: Does each instruction file show what good output looks like? -5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs? -6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"? -7. **Sync Complete**: Has `deepwork sync` been run successfully? -8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`? -9. **Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful. -**Review Process**: -1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above -2. The sub-agent should examine your outputs and verify each criterion is met -3. If the sub-agent identifies valid issues, fix them -4. Have the sub-agent review again until all valid feedback has been addressed -5. Only mark the step complete when the sub-agent confirms all criteria are satisfied - ## On Completion 1. Verify outputs are created diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index 83de5777..b9dfa066 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -21,140 +21,71 @@ agent: deepwork-jobs ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. ## Task Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** -> Update job instruction files -- **Bespoke learnings** (run-specific) -> Add to AGENTS.md +- **Generalizable learnings** - Update job instruction files +- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic -### Step 1: Analyze Conversation for Job Executions +### Process -1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns -2. **Identify the target folder** - Deepest common folder for future work on this topic -3. **If no job specified**, ask the user which job to analyze +1. **Analyze conversation for job executions** + - Scan for DeepWork slash commands (`/job_name.step_id`) + - Identify which jobs and steps were executed + - If unclear, run `git diff` to see where changes were made -### Step 2: Identify Issues +2. **Identify issues and patterns** + - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs + - **Inefficiency**: extra iterations, repeated information, missing context + - **Errors**: failed validations, edge cases, quality criteria issues + - **Successes**: what worked well, efficient approaches -Review the conversation for: +3. **Classify each learning** + - **Generalizable**: would help ANY future run (update instructions) + - **Doc spec-related**: improves document quality criteria (update doc specs) + - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) -**Confusion signals**: -- Unnecessary questions from the agent -- Misunderstandings about step requirements -- Incorrect outputs needing correction +4. **Update job instructions** (generalizable learnings) + - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` + - Keep concise - avoid redundancy + - Extract shared content to `steps/shared/` if needed -**Inefficiency signals**: -- Extra iterations needed -- Information repeated multiple times -- Missing context or dependencies +5. **Update doc specs** (if applicable) + - Edit `.deepwork/doc_specs/[doc_spec_name].md` + - Update quality criteria or document structure -**Error patterns**: -- Failed validations and why -- Misunderstood quality criteria -- Unhandled edge cases +6. **Create/update AGENTS.md** (bespoke learnings) + - Place in deepest common folder for the topic + - Use file references instead of duplicating content + - Pattern: "See `path/to/file.ext` for [description]" -**Success patterns**: -- What worked well -- Efficient approaches to preserve +7. **Update version and sync** + - Bump version in job.yml (patch for instructions, minor for criteria) + - Add changelog entry + - Run `deepwork sync` if instructions were modified -### Step 3: Classify Learnings +### File Reference Patterns -**Generalizable** (update instructions): -- Would help ANY future run of this job -- Addresses unclear or missing guidance -- Adds helpful examples - -**Doc spec-related** (update doc spec files): -- Improvements to document quality criteria -- Changes to document structure -- Updated audience or format info - -**Bespoke** (add to AGENTS.md): -- Specific to THIS project/codebase/run -- References specific files or paths -- Local conventions - -### Step 4: Update Job Instructions - -For generalizable learnings: - -1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` -2. Make targeted improvements - add context, examples, clarify ambiguity -3. Keep instructions concise - no redundancy -4. Preserve structure (Objective, Task, Output Format, Quality Criteria) -5. Note changes for changelog - -**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. - -### Step 5: Update Doc Spec Files (If Applicable) - -If doc spec learnings were identified: - -1. Find doc spec references in job.yml outputs -2. Update quality criteria with clearer requirements -3. Update example document if structure changed -4. Update metadata (audience, frequency, paths) - -### Step 6: Create/Update AGENTS.md - -For bespoke learnings: - -1. **Determine location** - Deepest common folder for the topic -2. **Use file references** - Link to source files rather than duplicating content -3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` - -**Good patterns** (references): +**Good (references)**: ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. - Error handling pattern: See `src/utils/errors.ts:15-30` ``` -**Avoid** (duplicating): +**Avoid (duplicating)**: ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` -### Step 7: Update Job Version and Changelog +## Output -If instruction files were modified: +- Updated instruction files (generalizable improvements) +- Updated doc specs (if applicable) +- AGENTS.md in the correct working folder (bespoke learnings) -1. Bump version (patch for improvements, minor for criteria changes) -2. Add changelog entry: - ```yaml - - version: "[new_version]" - changes: "Improved [step] based on execution learnings: [brief description]" - ``` - -### Step 8: Sync Skills - -If instructions were modified: -```bash -deepwork sync -``` - -## Quality Criteria - -- Conversation analyzed for job executions -- Learnings correctly classified (generalizable vs bespoke) -- Instructions updated for generalizable improvements -- Instructions remain concise -- Shared content extracted where appropriate -- AGENTS.md in correct folder with file references -- Sync complete if instructions modified -- When complete: `Quality Criteria Met` - -## Edge Cases - -**No job executions found**: Ask user which job to analyze - -**Multiple jobs executed**: Analyze each separately - -**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" - -**No issues found**: Document what worked well, consider adding as examples - -**Sensitive information**: Never include secrets or PII - reference config files instead +Include `Quality Criteria Met` when complete. ### Job Context @@ -196,32 +127,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - Do NOT proceed without required inputs; ask the user if any are missing - Do NOT modify files outside the scope of this step's defined outputs -## Quality Validation - -**Before completing this step, you MUST have your work reviewed against the quality criteria below.** - -Use a sub-agent (Haiku model) to review your work against these criteria: - -**Criteria (all must be satisfied)**: -1. **Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions? -2. **Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies? -3. **Instructions Improved**: Were job instructions updated to address identified issues? -4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity? -5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files? -6. **doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified? -7. **doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure? -8. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? -9. **File References Used**: Do AGENTS.md entries reference other files where appropriate? -10. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? -11. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? -12. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? -**Review Process**: -1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above -2. The sub-agent should examine your outputs and verify each criterion is met -3. If the sub-agent identifies valid issues, fix them -4. Have the sub-agent review again until all valid feedback has been addressed -5. Only mark the step complete when the sub-agent confirms all criteria are satisfied - ## On Completion 1. Verify outputs are created diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 6815da8c..6bbaee05 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -28,7 +28,7 @@ Before proceeding, confirm these steps are complete: ## Objective -Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists @@ -36,100 +36,47 @@ The define step focuses on understanding user requirements. This review step ens ## Task -Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. +Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. -### Step 1: Read the Job Specification +### Process -Read both files: -- `.deepwork/jobs/[job_name]/job.yml` - The specification to review -- `.deepwork/doc_specs/job_spec.md` - The quality criteria +1. **Read the files** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Read `.deepwork/doc_specs/job_spec.md` for reference -### Step 2: Spawn Review Sub-Agent +2. **Spawn review sub-agent** + - Use Task tool with `subagent_type: general-purpose` and `model: haiku` + - Include the full job.yml content and all 9 quality criteria in the prompt + - Request PASS/FAIL for each criterion with specific issues if failed -Use the Task tool with: -- `subagent_type`: "general-purpose" -- `model`: "haiku" -- `description`: "Review job.yml against doc spec" +3. **Fix failed criteria** + - Edit job.yml to address each failed criterion + - Common fixes: shorten summary, add changelog, fix dependencies -**Sub-agent prompt**: +4. **Re-run review if needed** + - Spawn a new sub-agent with updated content + - Repeat until all 9 criteria pass -``` -Review this job.yml against the following 9 quality criteria. +5. **Confirm completion** + - Announce "All 9 doc spec quality criteria pass" + - Include `Quality Criteria Met` + - Guide to next step: `/deepwork_jobs.implement` -For each criterion, respond with PASS or FAIL. -If FAIL: provide the specific issue and suggested fix. +### The 9 Quality Criteria -## job.yml Content - -[paste full job.yml content] - -## Quality Criteria - -1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) -2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) -3. **Concise Summary**: Under 200 characters, describes what job accomplishes -4. **Rich Description**: Multi-line explaining problem, process, outcomes, users -5. **Changelog Present**: Array with at least initial version entry -6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: Reference existing step IDs, no circular references -8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies -9. **Output Paths**: Valid filenames or paths - -## Response Format - -### Overall: [X/9 PASS] - -### Criterion Results -1. Valid Identifier: [PASS/FAIL] - [If FAIL: Issue and fix] -... - -### Summary of Required Fixes -[List fixes needed, or "No fixes required"] -``` - -### Step 3: Review Findings - -Parse the sub-agent's response: -1. Count passing criteria -2. Identify failures -3. Note suggested fixes - -### Step 4: Fix Failed Criteria - -Edit job.yml to address each failure: - -| Criterion | Common Fix | -|-----------|-----------| -| Valid Identifier | Convert to lowercase_underscores | -| Semantic Version | Set to `"1.0.0"` or fix format | -| Concise Summary | Shorten to <200 chars | -| Rich Description | Add multi-line explanation | -| Changelog Present | Add `changelog:` array | -| Complete Steps | Add missing required fields | -| Valid Dependencies | Fix step ID reference | -| Input Consistency | Add referenced step to dependencies | -| Output Paths | Use valid filename/path format | - -### Step 5: Re-Run Review (If Needed) - -If any criteria failed: -1. Spawn a new sub-agent with updated job.yml -2. Review new findings -3. Fix remaining issues -4. Repeat until all 9 criteria pass - -### Step 6: Confirm Completion - -When all 9 criteria pass: - -1. Announce: "All 9 doc spec quality criteria pass." -2. Include: `Quality Criteria Met` -3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." +1. **Valid Identifier**: lowercase with underscores, no spaces +2. **Semantic Version**: X.Y.Z format +3. **Concise Summary**: under 200 characters +4. **Rich Description**: multi-line with problem/process/outcome/users +5. **Changelog Present**: array with at least initial version +6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: reference existing steps, no circular refs +8. **Input Consistency**: from_step must be in dependencies +9. **Output Paths**: valid filenames or paths ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. +The validated `job.yml` file that passes all quality criteria. ### Job Context @@ -367,24 +314,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - Do NOT proceed without required inputs; ask the user if any are missing - Do NOT modify files outside the scope of this step's defined outputs -## Quality Validation - -**Before completing this step, you MUST have your work reviewed against the quality criteria below.** - -Use a sub-agent (Haiku model) to review your work against these criteria: - -**Criteria (all must be satisfied)**: -1. **Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review? -2. **All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria? -3. **Findings Addressed**: Were all failed criteria addressed by the main agent? -4. **Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed? -**Review Process**: -1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above -2. The sub-agent should examine your outputs and verify each criterion is met -3. If the sub-agent identifies valid issues, fix them -4. Have the sub-agent review again until all valid feedback has been addressed -5. Only mark the step complete when the sub-agent confirms all criteria are satisfied - ## On Completion 1. Verify outputs are created diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 3b14c068..6b806bc9 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "1.1.0" +version: "1.0.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -22,28 +22,26 @@ workflows: - implement changelog: - - version: "1.1.0" - changes: "Simplified step instructions to leverage deepwork-jobs expert; cleaned up redundant content; improved clarity and conciseness" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - - version: "0.9.0" - changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" - - version: "0.8.0" - changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" - - version: "0.7.0" - changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" - - version: "0.6.0" - changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation" - - version: "0.5.0" - changes: "Standardized on 'ask structured questions' phrasing for user input" - - version: "0.4.0" - changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" - - version: "0.3.0" - changes: "Added make_new_job.sh script and templates directory" - - version: "0.2.0" - changes: "Replaced refine command with learn command for conversation-driven improvement" - version: "0.1.0" changes: "Initial version" + - version: "0.2.0" + changes: "Replaced refine command with learn command for conversation-driven improvement" + - version: "0.3.0" + changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples" + - version: "0.4.0" + changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" + - version: "0.5.0" + changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions" + - version: "0.6.0" + changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation; learn.md now identifies and applies doc spec-related improvements" + - version: "0.7.0" + changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" + - version: "0.8.0" + changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" + - version: "0.9.0" + changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" steps: - id: define @@ -58,6 +56,7 @@ steps: - file: job.yml doc_spec: .deepwork/doc_specs/job_spec.md dependencies: [] + - id: review_job_spec name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." @@ -71,11 +70,6 @@ steps: doc_spec: .deepwork/doc_specs/job_spec.md dependencies: - define - quality_criteria: - - "**Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review?" - - "**All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria?" - - "**Findings Addressed**: Were all failed criteria addressed by the main agent?" - - "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?" - id: implement name: "Implement Job Steps" @@ -89,16 +83,6 @@ steps: - steps/ dependencies: - review_job_spec - quality_criteria: - - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?" - - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?" - - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?" - - "**Output Examples**: Does each instruction file show what good output looks like?" - - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?" - - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?" - - "**Sync Complete**: Has `deepwork sync` been run successfully?" - - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?" - - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful." - id: learn name: "Learn from Job Execution" @@ -112,16 +96,3 @@ steps: outputs: - AGENTS.md dependencies: [] - quality_criteria: - - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?" - - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?" - - "**Instructions Improved**: Were job instructions updated to address identified issues?" - - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?" - - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?" - - "**doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?" - - "**doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?" - - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?" - - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?" - - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?" - - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?" - - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?" diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index 237d2cd7..a9a6cd73 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -2,114 +2,51 @@ ## Objective -Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. +Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. ## Task -Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. +### Process -### Step 1: Understand the Job Purpose +1. **Understand the job purpose** + - Ask structured questions about the overall goal, domain, and frequency + - Understand what success looks like and who the audience is + - Identify the major phases of the workflow -Ask structured questions to understand what the user wants to accomplish: +2. **Detect document-oriented workflows** + - Look for patterns: "report", "summary", "monthly", "for stakeholders" + - If detected, offer to create a doc spec for consistent quality + - Use `.deepwork/doc_specs/job_spec.md` as a reference example -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) +3. **Define each step** + - For each phase, gather: purpose, inputs, outputs, dependencies + - Ask about output file paths and organization + - Consider whether steps need agent delegation -2. **What does success look like?** - - What's the final deliverable or outcome? - - Who is the audience for the output? +4. **Validate the workflow** + - Summarize the complete workflow + - Check for gaps in inputs/outputs between steps + - Confirm job name, summary, and version -3. **What are the major phases?** - - What are the distinct stages from start to finish? - - Are there any dependencies between phases? +5. **Create the job specification** + - Run `make_new_job.sh` to create directory structure: + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` + - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` -### Step 2: Detect Document-Oriented Workflows +### Key Guidelines -Check for document-focused patterns in the user's description: -- Keywords: "report", "summary", "document", "monthly", "quarterly" -- Final deliverable is a specific document type -- Recurring documents with consistent structure - -**If detected**, inform the user and ask if they want to: -- Create a doc spec for consistent document quality -- Use an existing doc spec from `.deepwork/doc_specs/` -- Skip doc spec and proceed with simple outputs - -See the expert's documentation on doc specs for the full schema and examples. - -### Step 3: Define Each Step - -For each major phase, gather: - -1. **Step Purpose**: What does this step accomplish? -2. **Inputs**: User parameters or files from previous steps -3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) -4. **Dependencies**: Which previous steps must complete first? -5. **Quality Criteria**: What makes a good vs. bad output? -6. **Agent Delegation**: Should this step run in a forked context? - -#### Work Product Storage Guidelines - -Job outputs belong in the main repository directory structure, not in dot-directories. - -**Good patterns**: -``` -competitive_research/competitors_list.md -operations/reports/2026-01/spending_analysis.md -``` - -**Avoid**: -``` -.deepwork/outputs/report.md # Hidden in dot-directory -output.md # Too generic -``` - -**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. - -**Supporting materials**: Place in `_dataroom` folder as peer to final output: -``` -operations/reports/2026-01/spending_analysis.md -operations/reports/2026-01/spending_analysis_dataroom/ - raw_data.csv - notes.md -``` - -### Step 4: Validate the Workflow - -After gathering all information: - -1. **Review the flow** - Summarize and show how outputs feed into the next step -2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies -3. **Confirm details** - Job name, summary (max 200 chars), description, version - -### Step 5: Create the Job Specification - -**First, create the directory structure**: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` - -**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` - -Refer to the expert for the complete job.yml schema. Key validation rules: -- Job name: lowercase, underscores only, no spaces -- Version: semantic versioning (start with 1.0.0) -- Summary: max 200 characters -- File inputs: `from_step` must be in dependencies -- At least one output per step - -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example +- **Ask structured questions** using the AskUserQuestion tool +- **Work products go in main repo**, not `.deepwork/` (for discoverability) +- **Use dates in paths** for periodic outputs that accumulate +- **Use `_dataroom` folders** for supporting materials +- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. +Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. -After creating the file: -1. Inform the user that the specification is complete -2. Recommend they review the job.yml file -3. Tell them to run `/deepwork_jobs.review_job_spec` next +After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md index bc1fa3d8..214338ea 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md @@ -2,105 +2,62 @@ ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. +Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. ## Task -Read the `job.yml` specification and create all necessary files to make the job functional. +Read the job.yml and create comprehensive instruction files for each step. -### Step 1: Create Directory Structure +### Process -Run the setup script: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` +1. **Create directory structure** (if needed) + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` -This creates: -- `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts -- `.deepwork/jobs/[job_name]/templates/` - Example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance +2. **Read and validate the specification** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Extract job name, description, and step details + - Understand the workflow structure -**Note**: If directory already exists from define step, create missing subdirectories manually. +3. **Generate step instruction files** + - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step + - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference + - Each file must include: Objective, Task, Process, Output Format, Quality Criteria -### Step 2: Read and Validate the Specification +4. **Sync skills** + ```bash + deepwork sync + ``` -1. Read `.deepwork/jobs/[job_name]/job.yml` -2. Validate structure (name, version, summary, description, steps) -3. Check dependencies are valid and non-circular -4. Extract step details for instruction generation +5. **Consider rules for the new job** + - Think about whether rules would help maintain quality + - If relevant, explain and offer to run `/deepwork_rules.define` -### Step 3: Generate Step Instruction Files +### Instruction File Guidelines -Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. +- **Be specific** - tailor to each step's purpose, not generic advice +- **Provide examples** - show what good output looks like +- **Include quality criteria** - how to verify the step is complete +- **Use "ask structured questions"** - for steps that gather user input +- **Align with hooks** - if step has hooks, match the validation criteria -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example +### Templates Available -**Guidelines**: - -1. **Use the job description** - It provides crucial context -2. **Be specific** - Tailor instructions to each step's purpose -3. **Provide examples** - Show what good output looks like -4. **Explain the "why"** - Help understand the step's role in the workflow -5. **Ask structured questions** - When a step has user inputs, MUST use this phrase -6. **Align with hooks** - If step has `hooks` defined, match quality criteria - -**Handling Hooks**: - -If a step has hooks defined, the instruction file should: -- Mirror the quality criteria that hooks will validate -- Be explicit about what success looks like -- Mention the `Quality Criteria Met` pattern when criteria are met - -### Step 4: Verify job.yml Location - -Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. - -### Step 5: Sync Skills - -Run: -```bash -deepwork sync -``` - -This generates skills for each step in `.claude/skills/` (or platform-specific directory). - -### Step 6: Consider Rules - -After implementing, consider whether **rules** would help enforce quality. - -**What are rules?** -Automated guardrails in `.deepwork/rules/` that trigger when files change. - -**When to suggest rules**: -- Job produces outputs that other files depend on -- Documentation should stay in sync with outputs -- Quality checks should happen when certain files change - -**Examples**: -| Job Type | Potential Rule | -|----------|----------------| -| API Design | Update docs when endpoints change | -| Database Schema | Review migrations when schema changes | -| Competitive Research | Update strategy when analysis changes | - -If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- Examples: `job.yml.example`, `step_instruction.md.example` ## Completion Checklist -Before marking complete: -- [ ] job.yml validated and in place -- [ ] All step instruction files created (complete, not stubs) +- [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined for each step -- [ ] User input steps use "ask structured questions" +- [ ] Quality criteria defined - [ ] `deepwork sync` executed successfully -- [ ] Skills available in platform directory -- [ ] Considered relevant rules for job domain +- [ ] Rules considered (suggest if genuinely helpful) ## Output -Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. +Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md index bae38c0e..f7175cb4 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -2,137 +2,68 @@ ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. ## Task Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** -> Update job instruction files -- **Bespoke learnings** (run-specific) -> Add to AGENTS.md +- **Generalizable learnings** - Update job instruction files +- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic -### Step 1: Analyze Conversation for Job Executions +### Process -1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns -2. **Identify the target folder** - Deepest common folder for future work on this topic -3. **If no job specified**, ask the user which job to analyze +1. **Analyze conversation for job executions** + - Scan for DeepWork slash commands (`/job_name.step_id`) + - Identify which jobs and steps were executed + - If unclear, run `git diff` to see where changes were made -### Step 2: Identify Issues +2. **Identify issues and patterns** + - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs + - **Inefficiency**: extra iterations, repeated information, missing context + - **Errors**: failed validations, edge cases, quality criteria issues + - **Successes**: what worked well, efficient approaches -Review the conversation for: +3. **Classify each learning** + - **Generalizable**: would help ANY future run (update instructions) + - **Doc spec-related**: improves document quality criteria (update doc specs) + - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) -**Confusion signals**: -- Unnecessary questions from the agent -- Misunderstandings about step requirements -- Incorrect outputs needing correction +4. **Update job instructions** (generalizable learnings) + - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` + - Keep concise - avoid redundancy + - Extract shared content to `steps/shared/` if needed -**Inefficiency signals**: -- Extra iterations needed -- Information repeated multiple times -- Missing context or dependencies +5. **Update doc specs** (if applicable) + - Edit `.deepwork/doc_specs/[doc_spec_name].md` + - Update quality criteria or document structure -**Error patterns**: -- Failed validations and why -- Misunderstood quality criteria -- Unhandled edge cases +6. **Create/update AGENTS.md** (bespoke learnings) + - Place in deepest common folder for the topic + - Use file references instead of duplicating content + - Pattern: "See `path/to/file.ext` for [description]" -**Success patterns**: -- What worked well -- Efficient approaches to preserve +7. **Update version and sync** + - Bump version in job.yml (patch for instructions, minor for criteria) + - Add changelog entry + - Run `deepwork sync` if instructions were modified -### Step 3: Classify Learnings +### File Reference Patterns -**Generalizable** (update instructions): -- Would help ANY future run of this job -- Addresses unclear or missing guidance -- Adds helpful examples - -**Doc spec-related** (update doc spec files): -- Improvements to document quality criteria -- Changes to document structure -- Updated audience or format info - -**Bespoke** (add to AGENTS.md): -- Specific to THIS project/codebase/run -- References specific files or paths -- Local conventions - -### Step 4: Update Job Instructions - -For generalizable learnings: - -1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` -2. Make targeted improvements - add context, examples, clarify ambiguity -3. Keep instructions concise - no redundancy -4. Preserve structure (Objective, Task, Output Format, Quality Criteria) -5. Note changes for changelog - -**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. - -### Step 5: Update Doc Spec Files (If Applicable) - -If doc spec learnings were identified: - -1. Find doc spec references in job.yml outputs -2. Update quality criteria with clearer requirements -3. Update example document if structure changed -4. Update metadata (audience, frequency, paths) - -### Step 6: Create/Update AGENTS.md - -For bespoke learnings: - -1. **Determine location** - Deepest common folder for the topic -2. **Use file references** - Link to source files rather than duplicating content -3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` - -**Good patterns** (references): +**Good (references)**: ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. - Error handling pattern: See `src/utils/errors.ts:15-30` ``` -**Avoid** (duplicating): +**Avoid (duplicating)**: ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` -### Step 7: Update Job Version and Changelog - -If instruction files were modified: - -1. Bump version (patch for improvements, minor for criteria changes) -2. Add changelog entry: - ```yaml - - version: "[new_version]" - changes: "Improved [step] based on execution learnings: [brief description]" - ``` - -### Step 8: Sync Skills - -If instructions were modified: -```bash -deepwork sync -``` - -## Quality Criteria - -- Conversation analyzed for job executions -- Learnings correctly classified (generalizable vs bespoke) -- Instructions updated for generalizable improvements -- Instructions remain concise -- Shared content extracted where appropriate -- AGENTS.md in correct folder with file references -- Sync complete if instructions modified -- When complete: `Quality Criteria Met` - -## Edge Cases - -**No job executions found**: Ask user which job to analyze - -**Multiple jobs executed**: Analyze each separately - -**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" +## Output -**No issues found**: Document what worked well, consider adding as examples +- Updated instruction files (generalizable improvements) +- Updated doc specs (if applicable) +- AGENTS.md in the correct working folder (bespoke learnings) -**Sensitive information**: Never include secrets or PII - reference config files instead +Include `Quality Criteria Met` when complete. diff --git a/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md b/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md index 87a2d7a9..621cfa6b 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md +++ b/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md @@ -2,7 +2,7 @@ ## Objective -Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists @@ -10,97 +10,44 @@ The define step focuses on understanding user requirements. This review step ens ## Task -Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. +Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. -### Step 1: Read the Job Specification +### Process -Read both files: -- `.deepwork/jobs/[job_name]/job.yml` - The specification to review -- `.deepwork/doc_specs/job_spec.md` - The quality criteria +1. **Read the files** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Read `.deepwork/doc_specs/job_spec.md` for reference -### Step 2: Spawn Review Sub-Agent +2. **Spawn review sub-agent** + - Use Task tool with `subagent_type: general-purpose` and `model: haiku` + - Include the full job.yml content and all 9 quality criteria in the prompt + - Request PASS/FAIL for each criterion with specific issues if failed -Use the Task tool with: -- `subagent_type`: "general-purpose" -- `model`: "haiku" -- `description`: "Review job.yml against doc spec" +3. **Fix failed criteria** + - Edit job.yml to address each failed criterion + - Common fixes: shorten summary, add changelog, fix dependencies -**Sub-agent prompt**: +4. **Re-run review if needed** + - Spawn a new sub-agent with updated content + - Repeat until all 9 criteria pass -``` -Review this job.yml against the following 9 quality criteria. +5. **Confirm completion** + - Announce "All 9 doc spec quality criteria pass" + - Include `Quality Criteria Met` + - Guide to next step: `/deepwork_jobs.implement` -For each criterion, respond with PASS or FAIL. -If FAIL: provide the specific issue and suggested fix. +### The 9 Quality Criteria -## job.yml Content - -[paste full job.yml content] - -## Quality Criteria - -1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) -2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) -3. **Concise Summary**: Under 200 characters, describes what job accomplishes -4. **Rich Description**: Multi-line explaining problem, process, outcomes, users -5. **Changelog Present**: Array with at least initial version entry -6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: Reference existing step IDs, no circular references -8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies -9. **Output Paths**: Valid filenames or paths - -## Response Format - -### Overall: [X/9 PASS] - -### Criterion Results -1. Valid Identifier: [PASS/FAIL] - [If FAIL: Issue and fix] -... - -### Summary of Required Fixes -[List fixes needed, or "No fixes required"] -``` - -### Step 3: Review Findings - -Parse the sub-agent's response: -1. Count passing criteria -2. Identify failures -3. Note suggested fixes - -### Step 4: Fix Failed Criteria - -Edit job.yml to address each failure: - -| Criterion | Common Fix | -|-----------|-----------| -| Valid Identifier | Convert to lowercase_underscores | -| Semantic Version | Set to `"1.0.0"` or fix format | -| Concise Summary | Shorten to <200 chars | -| Rich Description | Add multi-line explanation | -| Changelog Present | Add `changelog:` array | -| Complete Steps | Add missing required fields | -| Valid Dependencies | Fix step ID reference | -| Input Consistency | Add referenced step to dependencies | -| Output Paths | Use valid filename/path format | - -### Step 5: Re-Run Review (If Needed) - -If any criteria failed: -1. Spawn a new sub-agent with updated job.yml -2. Review new findings -3. Fix remaining issues -4. Repeat until all 9 criteria pass - -### Step 6: Confirm Completion - -When all 9 criteria pass: - -1. Announce: "All 9 doc spec quality criteria pass." -2. Include: `Quality Criteria Met` -3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." +1. **Valid Identifier**: lowercase with underscores, no spaces +2. **Semantic Version**: X.Y.Z format +3. **Concise Summary**: under 200 characters +4. **Rich Description**: multi-line with problem/process/outcome/users +5. **Changelog Present**: array with at least initial version +6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: reference existing steps, no circular refs +8. **Input Consistency**: from_step must be in dependencies +9. **Output Paths**: valid filenames or paths ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. +The validated `job.yml` file that passes all quality criteria. diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 68e1cd17..8c6ec898 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -22,117 +22,54 @@ prompt = """ ## Objective -Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. +Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. ## Task -Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. +### Process -### Step 1: Understand the Job Purpose +1. **Understand the job purpose** + - Ask structured questions about the overall goal, domain, and frequency + - Understand what success looks like and who the audience is + - Identify the major phases of the workflow -Ask structured questions to understand what the user wants to accomplish: +2. **Detect document-oriented workflows** + - Look for patterns: "report", "summary", "monthly", "for stakeholders" + - If detected, offer to create a doc spec for consistent quality + - Use `.deepwork/doc_specs/job_spec.md` as a reference example -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) +3. **Define each step** + - For each phase, gather: purpose, inputs, outputs, dependencies + - Ask about output file paths and organization + - Consider whether steps need agent delegation -2. **What does success look like?** - - What's the final deliverable or outcome? - - Who is the audience for the output? +4. **Validate the workflow** + - Summarize the complete workflow + - Check for gaps in inputs/outputs between steps + - Confirm job name, summary, and version -3. **What are the major phases?** - - What are the distinct stages from start to finish? - - Are there any dependencies between phases? +5. **Create the job specification** + - Run `make_new_job.sh` to create directory structure: + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` + - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` -### Step 2: Detect Document-Oriented Workflows +### Key Guidelines -Check for document-focused patterns in the user's description: -- Keywords: "report", "summary", "document", "monthly", "quarterly" -- Final deliverable is a specific document type -- Recurring documents with consistent structure - -**If detected**, inform the user and ask if they want to: -- Create a doc spec for consistent document quality -- Use an existing doc spec from `.deepwork/doc_specs/` -- Skip doc spec and proceed with simple outputs - -See the expert's documentation on doc specs for the full schema and examples. - -### Step 3: Define Each Step - -For each major phase, gather: - -1. **Step Purpose**: What does this step accomplish? -2. **Inputs**: User parameters or files from previous steps -3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) -4. **Dependencies**: Which previous steps must complete first? -5. **Quality Criteria**: What makes a good vs. bad output? -6. **Agent Delegation**: Should this step run in a forked context? - -#### Work Product Storage Guidelines - -Job outputs belong in the main repository directory structure, not in dot-directories. - -**Good patterns**: -``` -competitive_research/competitors_list.md -operations/reports/2026-01/spending_analysis.md -``` - -**Avoid**: -``` -.deepwork/outputs/report.md # Hidden in dot-directory -output.md # Too generic -``` - -**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. - -**Supporting materials**: Place in `_dataroom` folder as peer to final output: -``` -operations/reports/2026-01/spending_analysis.md -operations/reports/2026-01/spending_analysis_dataroom/ - raw_data.csv - notes.md -``` - -### Step 4: Validate the Workflow - -After gathering all information: - -1. **Review the flow** - Summarize and show how outputs feed into the next step -2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies -3. **Confirm details** - Job name, summary (max 200 chars), description, version - -### Step 5: Create the Job Specification - -**First, create the directory structure**: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` - -**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` - -Refer to the expert for the complete job.yml schema. Key validation rules: -- Job name: lowercase, underscores only, no spaces -- Version: semantic versioning (start with 1.0.0) -- Summary: max 200 characters -- File inputs: `from_step` must be in dependencies -- At least one output per step - -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example +- **Ask structured questions** using the AskUserQuestion tool +- **Work products go in main repo**, not `.deepwork/` (for discoverability) +- **Use dates in paths** for periodic outputs that accumulate +- **Use `_dataroom` folders** for supporting materials +- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. +Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. -After creating the file: -1. Inform the user that the specification is complete -2. Recommend they review the job.yml file -3. Tell them to run `/deepwork_jobs.review_job_spec` next +After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. ### Job Context diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml index 368ee3e2..b005e5a4 100644 --- a/.gemini/skills/deepwork_jobs/implement.toml +++ b/.gemini/skills/deepwork_jobs/implement.toml @@ -26,108 +26,65 @@ Before proceeding, confirm these steps are complete: ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. +Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. ## Task -Read the `job.yml` specification and create all necessary files to make the job functional. +Read the job.yml and create comprehensive instruction files for each step. -### Step 1: Create Directory Structure +### Process -Run the setup script: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` +1. **Create directory structure** (if needed) + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` -This creates: -- `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts -- `.deepwork/jobs/[job_name]/templates/` - Example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance +2. **Read and validate the specification** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Extract job name, description, and step details + - Understand the workflow structure -**Note**: If directory already exists from define step, create missing subdirectories manually. +3. **Generate step instruction files** + - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step + - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference + - Each file must include: Objective, Task, Process, Output Format, Quality Criteria -### Step 2: Read and Validate the Specification +4. **Sync skills** + ```bash + deepwork sync + ``` -1. Read `.deepwork/jobs/[job_name]/job.yml` -2. Validate structure (name, version, summary, description, steps) -3. Check dependencies are valid and non-circular -4. Extract step details for instruction generation +5. **Consider rules for the new job** + - Think about whether rules would help maintain quality + - If relevant, explain and offer to run `/deepwork_rules.define` -### Step 3: Generate Step Instruction Files +### Instruction File Guidelines -Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. +- **Be specific** - tailor to each step's purpose, not generic advice +- **Provide examples** - show what good output looks like +- **Include quality criteria** - how to verify the step is complete +- **Use "ask structured questions"** - for steps that gather user input +- **Align with hooks** - if step has hooks, match the validation criteria -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example +### Templates Available -**Guidelines**: - -1. **Use the job description** - It provides crucial context -2. **Be specific** - Tailor instructions to each step's purpose -3. **Provide examples** - Show what good output looks like -4. **Explain the "why"** - Help understand the step's role in the workflow -5. **Ask structured questions** - When a step has user inputs, MUST use this phrase -6. **Align with hooks** - If step has `hooks` defined, match quality criteria - -**Handling Hooks**: - -If a step has hooks defined, the instruction file should: -- Mirror the quality criteria that hooks will validate -- Be explicit about what success looks like -- Mention the `Quality Criteria Met` pattern when criteria are met - -### Step 4: Verify job.yml Location - -Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. - -### Step 5: Sync Skills - -Run: -```bash -deepwork sync -``` - -This generates skills for each step in `.claude/skills/` (or platform-specific directory). - -### Step 6: Consider Rules - -After implementing, consider whether **rules** would help enforce quality. - -**What are rules?** -Automated guardrails in `.deepwork/rules/` that trigger when files change. - -**When to suggest rules**: -- Job produces outputs that other files depend on -- Documentation should stay in sync with outputs -- Quality checks should happen when certain files change - -**Examples**: -| Job Type | Potential Rule | -|----------|----------------| -| API Design | Update docs when endpoints change | -| Database Schema | Review migrations when schema changes | -| Competitive Research | Update strategy when analysis changes | - -If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- Examples: `job.yml.example`, `step_instruction.md.example` ## Completion Checklist -Before marking complete: -- [ ] job.yml validated and in place -- [ ] All step instruction files created (complete, not stubs) +- [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined for each step -- [ ] User input steps use "ask structured questions" +- [ ] Quality criteria defined - [ ] `deepwork sync` executed successfully -- [ ] Skills available in platform directory -- [ ] Considered relevant rules for job domain +- [ ] Rules considered (suggest if genuinely helpful) ## Output -Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. +Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. ### Job Context @@ -162,20 +119,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` **Required outputs**: - `steps/` (directory) -## Quality Validation (Manual) - -**NOTE**: Gemini CLI does not support automated validation. Manually verify criteria before completing. - -**Criteria (all must be satisfied)**: -1. **Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly? -2. **Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)? -3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic? -4. **Output Examples**: Does each instruction file show what good output looks like? -5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs? -6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"? -7. **Sync Complete**: Has `deepwork sync` been run successfully? -8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`? -9. **Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful. ## On Completion 1. Verify outputs are created diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index 23ea6c61..76311171 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -22,140 +22,71 @@ prompt = """ ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. ## Task Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** -> Update job instruction files -- **Bespoke learnings** (run-specific) -> Add to AGENTS.md +- **Generalizable learnings** - Update job instruction files +- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic -### Step 1: Analyze Conversation for Job Executions +### Process -1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns -2. **Identify the target folder** - Deepest common folder for future work on this topic -3. **If no job specified**, ask the user which job to analyze +1. **Analyze conversation for job executions** + - Scan for DeepWork slash commands (`/job_name.step_id`) + - Identify which jobs and steps were executed + - If unclear, run `git diff` to see where changes were made -### Step 2: Identify Issues +2. **Identify issues and patterns** + - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs + - **Inefficiency**: extra iterations, repeated information, missing context + - **Errors**: failed validations, edge cases, quality criteria issues + - **Successes**: what worked well, efficient approaches -Review the conversation for: +3. **Classify each learning** + - **Generalizable**: would help ANY future run (update instructions) + - **Doc spec-related**: improves document quality criteria (update doc specs) + - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) -**Confusion signals**: -- Unnecessary questions from the agent -- Misunderstandings about step requirements -- Incorrect outputs needing correction +4. **Update job instructions** (generalizable learnings) + - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` + - Keep concise - avoid redundancy + - Extract shared content to `steps/shared/` if needed -**Inefficiency signals**: -- Extra iterations needed -- Information repeated multiple times -- Missing context or dependencies +5. **Update doc specs** (if applicable) + - Edit `.deepwork/doc_specs/[doc_spec_name].md` + - Update quality criteria or document structure -**Error patterns**: -- Failed validations and why -- Misunderstood quality criteria -- Unhandled edge cases +6. **Create/update AGENTS.md** (bespoke learnings) + - Place in deepest common folder for the topic + - Use file references instead of duplicating content + - Pattern: "See `path/to/file.ext` for [description]" -**Success patterns**: -- What worked well -- Efficient approaches to preserve +7. **Update version and sync** + - Bump version in job.yml (patch for instructions, minor for criteria) + - Add changelog entry + - Run `deepwork sync` if instructions were modified -### Step 3: Classify Learnings +### File Reference Patterns -**Generalizable** (update instructions): -- Would help ANY future run of this job -- Addresses unclear or missing guidance -- Adds helpful examples - -**Doc spec-related** (update doc spec files): -- Improvements to document quality criteria -- Changes to document structure -- Updated audience or format info - -**Bespoke** (add to AGENTS.md): -- Specific to THIS project/codebase/run -- References specific files or paths -- Local conventions - -### Step 4: Update Job Instructions - -For generalizable learnings: - -1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` -2. Make targeted improvements - add context, examples, clarify ambiguity -3. Keep instructions concise - no redundancy -4. Preserve structure (Objective, Task, Output Format, Quality Criteria) -5. Note changes for changelog - -**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. - -### Step 5: Update Doc Spec Files (If Applicable) - -If doc spec learnings were identified: - -1. Find doc spec references in job.yml outputs -2. Update quality criteria with clearer requirements -3. Update example document if structure changed -4. Update metadata (audience, frequency, paths) - -### Step 6: Create/Update AGENTS.md - -For bespoke learnings: - -1. **Determine location** - Deepest common folder for the topic -2. **Use file references** - Link to source files rather than duplicating content -3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` - -**Good patterns** (references): +**Good (references)**: ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. - Error handling pattern: See `src/utils/errors.ts:15-30` ``` -**Avoid** (duplicating): +**Avoid (duplicating)**: ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` -### Step 7: Update Job Version and Changelog - -If instruction files were modified: - -1. Bump version (patch for improvements, minor for criteria changes) -2. Add changelog entry: - ```yaml - - version: "[new_version]" - changes: "Improved [step] based on execution learnings: [brief description]" - ``` - -### Step 8: Sync Skills - -If instructions were modified: -```bash -deepwork sync -``` - -## Quality Criteria - -- Conversation analyzed for job executions -- Learnings correctly classified (generalizable vs bespoke) -- Instructions updated for generalizable improvements -- Instructions remain concise -- Shared content extracted where appropriate -- AGENTS.md in correct folder with file references -- Sync complete if instructions modified -- When complete: `Quality Criteria Met` - -## Edge Cases - -**No job executions found**: Ask user which job to analyze - -**Multiple jobs executed**: Analyze each separately - -**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" +## Output -**No issues found**: Document what worked well, consider adding as examples +- Updated instruction files (generalizable improvements) +- Updated doc specs (if applicable) +- AGENTS.md in the correct working folder (bespoke learnings) -**Sensitive information**: Never include secrets or PII - reference config files instead +Include `Quality Criteria Met` when complete. ### Job Context @@ -190,23 +121,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` **Required outputs**: - `AGENTS.md` -## Quality Validation (Manual) - -**NOTE**: Gemini CLI does not support automated validation. Manually verify criteria before completing. - -**Criteria (all must be satisfied)**: -1. **Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions? -2. **Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies? -3. **Instructions Improved**: Were job instructions updated to address identified issues? -4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity? -5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files? -6. **doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified? -7. **doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure? -8. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? -9. **File References Used**: Do AGENTS.md entries reference other files where appropriate? -10. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? -11. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? -12. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? ## On Completion 1. Verify outputs are created diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index 1fa1e2c5..9d917093 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -26,7 +26,7 @@ Before proceeding, confirm these steps are complete: ## Objective -Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists @@ -34,100 +34,47 @@ The define step focuses on understanding user requirements. This review step ens ## Task -Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. +Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. -### Step 1: Read the Job Specification +### Process -Read both files: -- `.deepwork/jobs/[job_name]/job.yml` - The specification to review -- `.deepwork/doc_specs/job_spec.md` - The quality criteria +1. **Read the files** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Read `.deepwork/doc_specs/job_spec.md` for reference -### Step 2: Spawn Review Sub-Agent +2. **Spawn review sub-agent** + - Use Task tool with `subagent_type: general-purpose` and `model: haiku` + - Include the full job.yml content and all 9 quality criteria in the prompt + - Request PASS/FAIL for each criterion with specific issues if failed -Use the Task tool with: -- `subagent_type`: "general-purpose" -- `model`: "haiku" -- `description`: "Review job.yml against doc spec" +3. **Fix failed criteria** + - Edit job.yml to address each failed criterion + - Common fixes: shorten summary, add changelog, fix dependencies -**Sub-agent prompt**: +4. **Re-run review if needed** + - Spawn a new sub-agent with updated content + - Repeat until all 9 criteria pass -``` -Review this job.yml against the following 9 quality criteria. +5. **Confirm completion** + - Announce "All 9 doc spec quality criteria pass" + - Include `Quality Criteria Met` + - Guide to next step: `/deepwork_jobs.implement` -For each criterion, respond with PASS or FAIL. -If FAIL: provide the specific issue and suggested fix. +### The 9 Quality Criteria -## job.yml Content - -[paste full job.yml content] - -## Quality Criteria - -1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) -2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) -3. **Concise Summary**: Under 200 characters, describes what job accomplishes -4. **Rich Description**: Multi-line explaining problem, process, outcomes, users -5. **Changelog Present**: Array with at least initial version entry -6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: Reference existing step IDs, no circular references -8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies -9. **Output Paths**: Valid filenames or paths - -## Response Format - -### Overall: [X/9 PASS] - -### Criterion Results -1. Valid Identifier: [PASS/FAIL] - [If FAIL: Issue and fix] -... - -### Summary of Required Fixes -[List fixes needed, or "No fixes required"] -``` - -### Step 3: Review Findings - -Parse the sub-agent's response: -1. Count passing criteria -2. Identify failures -3. Note suggested fixes - -### Step 4: Fix Failed Criteria - -Edit job.yml to address each failure: - -| Criterion | Common Fix | -|-----------|-----------| -| Valid Identifier | Convert to lowercase_underscores | -| Semantic Version | Set to `"1.0.0"` or fix format | -| Concise Summary | Shorten to <200 chars | -| Rich Description | Add multi-line explanation | -| Changelog Present | Add `changelog:` array | -| Complete Steps | Add missing required fields | -| Valid Dependencies | Fix step ID reference | -| Input Consistency | Add referenced step to dependencies | -| Output Paths | Use valid filename/path format | - -### Step 5: Re-Run Review (If Needed) - -If any criteria failed: -1. Spawn a new sub-agent with updated job.yml -2. Review new findings -3. Fix remaining issues -4. Repeat until all 9 criteria pass - -### Step 6: Confirm Completion - -When all 9 criteria pass: - -1. Announce: "All 9 doc spec quality criteria pass." -2. Include: `Quality Criteria Met` -3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." +1. **Valid Identifier**: lowercase with underscores, no spaces +2. **Semantic Version**: X.Y.Z format +3. **Concise Summary**: under 200 characters +4. **Rich Description**: multi-line with problem/process/outcome/users +5. **Changelog Present**: array with at least initial version +6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: reference existing steps, no circular refs +8. **Input Consistency**: from_step must be in dependencies +9. **Output Paths**: valid filenames or paths ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. +The validated `job.yml` file that passes all quality criteria. ### Job Context @@ -177,15 +124,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 9. **Output Paths**: Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`). 10. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI. -## Quality Validation (Manual) - -**NOTE**: Gemini CLI does not support automated validation. Manually verify criteria before completing. - -**Criteria (all must be satisfied)**: -1. **Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review? -2. **All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria? -3. **Findings Addressed**: Were all failed criteria addressed by the main agent? -4. **Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed? ## On Completion 1. Verify outputs are created diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 3b14c068..6b806bc9 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "1.1.0" +version: "1.0.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -22,28 +22,26 @@ workflows: - implement changelog: - - version: "1.1.0" - changes: "Simplified step instructions to leverage deepwork-jobs expert; cleaned up redundant content; improved clarity and conciseness" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - - version: "0.9.0" - changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" - - version: "0.8.0" - changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" - - version: "0.7.0" - changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" - - version: "0.6.0" - changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation" - - version: "0.5.0" - changes: "Standardized on 'ask structured questions' phrasing for user input" - - version: "0.4.0" - changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" - - version: "0.3.0" - changes: "Added make_new_job.sh script and templates directory" - - version: "0.2.0" - changes: "Replaced refine command with learn command for conversation-driven improvement" - version: "0.1.0" changes: "Initial version" + - version: "0.2.0" + changes: "Replaced refine command with learn command for conversation-driven improvement" + - version: "0.3.0" + changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples" + - version: "0.4.0" + changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" + - version: "0.5.0" + changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions" + - version: "0.6.0" + changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation; learn.md now identifies and applies doc spec-related improvements" + - version: "0.7.0" + changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation" + - version: "0.8.0" + changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review" + - version: "0.9.0" + changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" steps: - id: define @@ -58,6 +56,7 @@ steps: - file: job.yml doc_spec: .deepwork/doc_specs/job_spec.md dependencies: [] + - id: review_job_spec name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." @@ -71,11 +70,6 @@ steps: doc_spec: .deepwork/doc_specs/job_spec.md dependencies: - define - quality_criteria: - - "**Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review?" - - "**All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria?" - - "**Findings Addressed**: Were all failed criteria addressed by the main agent?" - - "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?" - id: implement name: "Implement Job Steps" @@ -89,16 +83,6 @@ steps: - steps/ dependencies: - review_job_spec - quality_criteria: - - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?" - - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?" - - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?" - - "**Output Examples**: Does each instruction file show what good output looks like?" - - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?" - - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?" - - "**Sync Complete**: Has `deepwork sync` been run successfully?" - - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?" - - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful." - id: learn name: "Learn from Job Execution" @@ -112,16 +96,3 @@ steps: outputs: - AGENTS.md dependencies: [] - quality_criteria: - - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?" - - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?" - - "**Instructions Improved**: Were job instructions updated to address identified issues?" - - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?" - - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?" - - "**doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?" - - "**doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?" - - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?" - - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?" - - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?" - - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?" - - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 237d2cd7..a9a6cd73 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -2,114 +2,51 @@ ## Objective -Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions. +Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. ## Task -Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step. +### Process -### Step 1: Understand the Job Purpose +1. **Understand the job purpose** + - Ask structured questions about the overall goal, domain, and frequency + - Understand what success looks like and who the audience is + - Identify the major phases of the workflow -Ask structured questions to understand what the user wants to accomplish: +2. **Detect document-oriented workflows** + - Look for patterns: "report", "summary", "monthly", "for stakeholders" + - If detected, offer to create a doc spec for consistent quality + - Use `.deepwork/doc_specs/job_spec.md` as a reference example -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) +3. **Define each step** + - For each phase, gather: purpose, inputs, outputs, dependencies + - Ask about output file paths and organization + - Consider whether steps need agent delegation -2. **What does success look like?** - - What's the final deliverable or outcome? - - Who is the audience for the output? +4. **Validate the workflow** + - Summarize the complete workflow + - Check for gaps in inputs/outputs between steps + - Confirm job name, summary, and version -3. **What are the major phases?** - - What are the distinct stages from start to finish? - - Are there any dependencies between phases? +5. **Create the job specification** + - Run `make_new_job.sh` to create directory structure: + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` + - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` -### Step 2: Detect Document-Oriented Workflows +### Key Guidelines -Check for document-focused patterns in the user's description: -- Keywords: "report", "summary", "document", "monthly", "quarterly" -- Final deliverable is a specific document type -- Recurring documents with consistent structure - -**If detected**, inform the user and ask if they want to: -- Create a doc spec for consistent document quality -- Use an existing doc spec from `.deepwork/doc_specs/` -- Skip doc spec and proceed with simple outputs - -See the expert's documentation on doc specs for the full schema and examples. - -### Step 3: Define Each Step - -For each major phase, gather: - -1. **Step Purpose**: What does this step accomplish? -2. **Inputs**: User parameters or files from previous steps -3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below) -4. **Dependencies**: Which previous steps must complete first? -5. **Quality Criteria**: What makes a good vs. bad output? -6. **Agent Delegation**: Should this step run in a forked context? - -#### Work Product Storage Guidelines - -Job outputs belong in the main repository directory structure, not in dot-directories. - -**Good patterns**: -``` -competitive_research/competitors_list.md -operations/reports/2026-01/spending_analysis.md -``` - -**Avoid**: -``` -.deepwork/outputs/report.md # Hidden in dot-directory -output.md # Too generic -``` - -**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents. - -**Supporting materials**: Place in `_dataroom` folder as peer to final output: -``` -operations/reports/2026-01/spending_analysis.md -operations/reports/2026-01/spending_analysis_dataroom/ - raw_data.csv - notes.md -``` - -### Step 4: Validate the Workflow - -After gathering all information: - -1. **Review the flow** - Summarize and show how outputs feed into the next step -2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies -3. **Confirm details** - Job name, summary (max 200 chars), description, version - -### Step 5: Create the Job Specification - -**First, create the directory structure**: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` - -**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml` - -Refer to the expert for the complete job.yml schema. Key validation rules: -- Job name: lowercase, underscores only, no spaces -- Version: semantic versioning (start with 1.0.0) -- Summary: max 200 characters -- File inputs: `from_step` must be in dependencies -- At least one output per step - -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example +- **Ask structured questions** using the AskUserQuestion tool +- **Work products go in main repo**, not `.deepwork/` (for discoverability) +- **Use dates in paths** for periodic outputs that accumulate +- **Use `_dataroom` folders** for supporting materials +- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`. +Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. -After creating the file: -1. Inform the user that the specification is complete -2. Recommend they review the job.yml file -3. Tell them to run `/deepwork_jobs.review_job_spec` next +After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index bc1fa3d8..214338ea 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -2,105 +2,62 @@ ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. +Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. ## Task -Read the `job.yml` specification and create all necessary files to make the job functional. +Read the job.yml and create comprehensive instruction files for each step. -### Step 1: Create Directory Structure +### Process -Run the setup script: -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` +1. **Create directory structure** (if needed) + ```bash + .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + ``` -This creates: -- `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts -- `.deepwork/jobs/[job_name]/templates/` - Example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance +2. **Read and validate the specification** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Extract job name, description, and step details + - Understand the workflow structure -**Note**: If directory already exists from define step, create missing subdirectories manually. +3. **Generate step instruction files** + - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step + - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference + - Each file must include: Objective, Task, Process, Output Format, Quality Criteria -### Step 2: Read and Validate the Specification +4. **Sync skills** + ```bash + deepwork sync + ``` -1. Read `.deepwork/jobs/[job_name]/job.yml` -2. Validate structure (name, version, summary, description, steps) -3. Check dependencies are valid and non-circular -4. Extract step details for instruction generation +5. **Consider rules for the new job** + - Think about whether rules would help maintain quality + - If relevant, explain and offer to run `/deepwork_rules.define` -### Step 3: Generate Step Instruction Files +### Instruction File Guidelines -Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step. +- **Be specific** - tailor to each step's purpose, not generic advice +- **Provide examples** - show what good output looks like +- **Include quality criteria** - how to verify the step is complete +- **Use "ask structured questions"** - for steps that gather user input +- **Align with hooks** - if step has hooks, match the validation criteria -**Templates**: -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure -- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example +### Templates Available -**Guidelines**: - -1. **Use the job description** - It provides crucial context -2. **Be specific** - Tailor instructions to each step's purpose -3. **Provide examples** - Show what good output looks like -4. **Explain the "why"** - Help understand the step's role in the workflow -5. **Ask structured questions** - When a step has user inputs, MUST use this phrase -6. **Align with hooks** - If step has `hooks` defined, match quality criteria - -**Handling Hooks**: - -If a step has hooks defined, the instruction file should: -- Mirror the quality criteria that hooks will validate -- Be explicit about what success looks like -- Mention the `Quality Criteria Met` pattern when criteria are met - -### Step 4: Verify job.yml Location - -Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`. - -### Step 5: Sync Skills - -Run: -```bash -deepwork sync -``` - -This generates skills for each step in `.claude/skills/` (or platform-specific directory). - -### Step 6: Consider Rules - -After implementing, consider whether **rules** would help enforce quality. - -**What are rules?** -Automated guardrails in `.deepwork/rules/` that trigger when files change. - -**When to suggest rules**: -- Job produces outputs that other files depend on -- Documentation should stay in sync with outputs -- Quality checks should happen when certain files change - -**Examples**: -| Job Type | Potential Rule | -|----------|----------------| -| API Design | Update docs when endpoints change | -| Database Schema | Review migrations when schema changes | -| Competitive Research | Update strategy when analysis changes | - -If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`. +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- Examples: `job.yml.example`, `step_instruction.md.example` ## Completion Checklist -Before marking complete: -- [ ] job.yml validated and in place -- [ ] All step instruction files created (complete, not stubs) +- [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined for each step -- [ ] User input steps use "ask structured questions" +- [ ] Quality criteria defined - [ ] `deepwork sync` executed successfully -- [ ] Skills available in platform directory -- [ ] Considered relevant rules for job domain +- [ ] Rules considered (suggest if genuinely helpful) ## Output -Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills. +Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index bae38c0e..f7175cb4 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -2,137 +2,68 @@ ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke learnings in AGENTS.md. +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. ## Task Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** -> Update job instruction files -- **Bespoke learnings** (run-specific) -> Add to AGENTS.md +- **Generalizable learnings** - Update job instruction files +- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic -### Step 1: Analyze Conversation for Job Executions +### Process -1. **Scan for DeepWork commands** - Look for `/job_name.step_id` patterns -2. **Identify the target folder** - Deepest common folder for future work on this topic -3. **If no job specified**, ask the user which job to analyze +1. **Analyze conversation for job executions** + - Scan for DeepWork slash commands (`/job_name.step_id`) + - Identify which jobs and steps were executed + - If unclear, run `git diff` to see where changes were made -### Step 2: Identify Issues +2. **Identify issues and patterns** + - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs + - **Inefficiency**: extra iterations, repeated information, missing context + - **Errors**: failed validations, edge cases, quality criteria issues + - **Successes**: what worked well, efficient approaches -Review the conversation for: +3. **Classify each learning** + - **Generalizable**: would help ANY future run (update instructions) + - **Doc spec-related**: improves document quality criteria (update doc specs) + - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) -**Confusion signals**: -- Unnecessary questions from the agent -- Misunderstandings about step requirements -- Incorrect outputs needing correction +4. **Update job instructions** (generalizable learnings) + - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` + - Keep concise - avoid redundancy + - Extract shared content to `steps/shared/` if needed -**Inefficiency signals**: -- Extra iterations needed -- Information repeated multiple times -- Missing context or dependencies +5. **Update doc specs** (if applicable) + - Edit `.deepwork/doc_specs/[doc_spec_name].md` + - Update quality criteria or document structure -**Error patterns**: -- Failed validations and why -- Misunderstood quality criteria -- Unhandled edge cases +6. **Create/update AGENTS.md** (bespoke learnings) + - Place in deepest common folder for the topic + - Use file references instead of duplicating content + - Pattern: "See `path/to/file.ext` for [description]" -**Success patterns**: -- What worked well -- Efficient approaches to preserve +7. **Update version and sync** + - Bump version in job.yml (patch for instructions, minor for criteria) + - Add changelog entry + - Run `deepwork sync` if instructions were modified -### Step 3: Classify Learnings +### File Reference Patterns -**Generalizable** (update instructions): -- Would help ANY future run of this job -- Addresses unclear or missing guidance -- Adds helpful examples - -**Doc spec-related** (update doc spec files): -- Improvements to document quality criteria -- Changes to document structure -- Updated audience or format info - -**Bespoke** (add to AGENTS.md): -- Specific to THIS project/codebase/run -- References specific files or paths -- Local conventions - -### Step 4: Update Job Instructions - -For generalizable learnings: - -1. Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` -2. Make targeted improvements - add context, examples, clarify ambiguity -3. Keep instructions concise - no redundancy -4. Preserve structure (Objective, Task, Output Format, Quality Criteria) -5. Note changes for changelog - -**Extract shared content**: If content appears in multiple steps, move to `.deepwork/jobs/[job_name]/steps/shared/`. - -### Step 5: Update Doc Spec Files (If Applicable) - -If doc spec learnings were identified: - -1. Find doc spec references in job.yml outputs -2. Update quality criteria with clearer requirements -3. Update example document if structure changed -4. Update metadata (audience, frequency, paths) - -### Step 6: Create/Update AGENTS.md - -For bespoke learnings: - -1. **Determine location** - Deepest common folder for the topic -2. **Use file references** - Link to source files rather than duplicating content -3. **Structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` - -**Good patterns** (references): +**Good (references)**: ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. - Error handling pattern: See `src/utils/errors.ts:15-30` ``` -**Avoid** (duplicating): +**Avoid (duplicating)**: ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` -### Step 7: Update Job Version and Changelog - -If instruction files were modified: - -1. Bump version (patch for improvements, minor for criteria changes) -2. Add changelog entry: - ```yaml - - version: "[new_version]" - changes: "Improved [step] based on execution learnings: [brief description]" - ``` - -### Step 8: Sync Skills - -If instructions were modified: -```bash -deepwork sync -``` - -## Quality Criteria - -- Conversation analyzed for job executions -- Learnings correctly classified (generalizable vs bespoke) -- Instructions updated for generalizable improvements -- Instructions remain concise -- Shared content extracted where appropriate -- AGENTS.md in correct folder with file references -- Sync complete if instructions modified -- When complete: `Quality Criteria Met` - -## Edge Cases - -**No job executions found**: Ask user which job to analyze - -**Multiple jobs executed**: Analyze each separately - -**AGENTS.md exists**: Read existing, append new learnings, update "Last Updated" +## Output -**No issues found**: Document what worked well, consider adding as examples +- Updated instruction files (generalizable improvements) +- Updated doc specs (if applicable) +- AGENTS.md in the correct working folder (bespoke learnings) -**Sensitive information**: Never include secrets or PII - reference config files instead +Include `Quality Criteria Met` when complete. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md index 87a2d7a9..621cfa6b 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md @@ -2,7 +2,7 @@ ## Objective -Review the `job.yml` created in the define step against quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. ## Why This Step Exists @@ -10,97 +10,44 @@ The define step focuses on understanding user requirements. This review step ens ## Task -Use a sub-agent to review the job.yml against doc spec quality criteria, fix any failures, and repeat until all pass. +Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. -### Step 1: Read the Job Specification +### Process -Read both files: -- `.deepwork/jobs/[job_name]/job.yml` - The specification to review -- `.deepwork/doc_specs/job_spec.md` - The quality criteria +1. **Read the files** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Read `.deepwork/doc_specs/job_spec.md` for reference -### Step 2: Spawn Review Sub-Agent +2. **Spawn review sub-agent** + - Use Task tool with `subagent_type: general-purpose` and `model: haiku` + - Include the full job.yml content and all 9 quality criteria in the prompt + - Request PASS/FAIL for each criterion with specific issues if failed -Use the Task tool with: -- `subagent_type`: "general-purpose" -- `model`: "haiku" -- `description`: "Review job.yml against doc spec" +3. **Fix failed criteria** + - Edit job.yml to address each failed criterion + - Common fixes: shorten summary, add changelog, fix dependencies -**Sub-agent prompt**: +4. **Re-run review if needed** + - Spawn a new sub-agent with updated content + - Repeat until all 9 criteria pass -``` -Review this job.yml against the following 9 quality criteria. +5. **Confirm completion** + - Announce "All 9 doc spec quality criteria pass" + - Include `Quality Criteria Met` + - Guide to next step: `/deepwork_jobs.implement` -For each criterion, respond with PASS or FAIL. -If FAIL: provide the specific issue and suggested fix. +### The 9 Quality Criteria -## job.yml Content - -[paste full job.yml content] - -## Quality Criteria - -1. **Valid Identifier**: Job name lowercase with underscores (e.g., `competitive_research`) -2. **Semantic Version**: Format X.Y.Z (e.g., `1.0.0`) -3. **Concise Summary**: Under 200 characters, describes what job accomplishes -4. **Rich Description**: Multi-line explaining problem, process, outcomes, users -5. **Changelog Present**: Array with at least initial version entry -6. **Complete Steps**: Each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: Reference existing step IDs, no circular references -8. **Input Consistency**: File inputs with `from_step` reference a step in dependencies -9. **Output Paths**: Valid filenames or paths - -## Response Format - -### Overall: [X/9 PASS] - -### Criterion Results -1. Valid Identifier: [PASS/FAIL] - [If FAIL: Issue and fix] -... - -### Summary of Required Fixes -[List fixes needed, or "No fixes required"] -``` - -### Step 3: Review Findings - -Parse the sub-agent's response: -1. Count passing criteria -2. Identify failures -3. Note suggested fixes - -### Step 4: Fix Failed Criteria - -Edit job.yml to address each failure: - -| Criterion | Common Fix | -|-----------|-----------| -| Valid Identifier | Convert to lowercase_underscores | -| Semantic Version | Set to `"1.0.0"` or fix format | -| Concise Summary | Shorten to <200 chars | -| Rich Description | Add multi-line explanation | -| Changelog Present | Add `changelog:` array | -| Complete Steps | Add missing required fields | -| Valid Dependencies | Fix step ID reference | -| Input Consistency | Add referenced step to dependencies | -| Output Paths | Use valid filename/path format | - -### Step 5: Re-Run Review (If Needed) - -If any criteria failed: -1. Spawn a new sub-agent with updated job.yml -2. Review new findings -3. Fix remaining issues -4. Repeat until all 9 criteria pass - -### Step 6: Confirm Completion - -When all 9 criteria pass: - -1. Announce: "All 9 doc spec quality criteria pass." -2. Include: `Quality Criteria Met` -3. Guide: "Run `/deepwork_jobs.implement` to generate step instruction files." +1. **Valid Identifier**: lowercase with underscores, no spaces +2. **Semantic Version**: X.Y.Z format +3. **Concise Summary**: under 200 characters +4. **Rich Description**: multi-line with problem/process/outcome/users +5. **Changelog Present**: array with at least initial version +6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies**: reference existing steps, no circular refs +8. **Input Consistency**: from_step must be in dependencies +9. **Output Paths**: valid filenames or paths ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` passing all 9 quality criteria. +The validated `job.yml` file that passes all quality criteria. From cab5e2f7a74103e8fb37cfd9739e6995f41df836 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 1 Feb 2026 10:14:23 -0700 Subject: [PATCH 8/9] revert jobs --- .claude/skills/add_platform/SKILL.md | 2 +- .claude/skills/commit/SKILL.md | 2 +- .claude/skills/deepwork_jobs.define/SKILL.md | 2 +- .claude/skills/deepwork_jobs/SKILL.md | 2 +- .claude/skills/deepwork_rules.define/SKILL.md | 2 +- .claude/skills/deepwork_rules/SKILL.md | 2 +- .claude/skills/manual_tests/SKILL.md | 2 +- .claude/skills/update/SKILL.md | 2 +- .../deepwork_jobs/topics/step_instructions.md | 14 +- .deepwork/jobs/deepwork_jobs/AGENTS.md | 34 +- .deepwork/jobs/deepwork_jobs/steps/define.md | 2 +- .deepwork/jobs/deepwork_rules/steps/define.md | 2 +- .gemini/skills/deepwork_jobs/define.toml | 2 +- .gemini/skills/deepwork_rules/define.toml | 2 +- .../spec_driven_development/steps/clarify.md | 2 +- .../steps/constitution.md | 2 +- .../spec_driven_development/steps/plan.md | 2 +- .../spec_driven_development/steps/specify.md | 7 +- .../deepwork_jobs/topics/step_instructions.md | 14 +- .../standard_jobs/deepwork_jobs/job.yml | 33 +- .../deepwork_jobs/steps/define.md | 472 ++++++++++++++++-- .../deepwork_jobs/steps/implement.md | 248 +++++++-- .../deepwork_jobs/steps/learn.md | 370 ++++++++++++-- .../deepwork_jobs/steps/review_job_spec.md | 217 ++++++-- .../deepwork_rules/steps/define.md | 2 +- .../templates/claude/skill-job-meta.md.jinja | 2 +- 26 files changed, 1255 insertions(+), 188 deletions(-) diff --git a/.claude/skills/add_platform/SKILL.md b/.claude/skills/add_platform/SKILL.md index 474bb3a8..9c56af25 100644 --- a/.claude/skills/add_platform/SKILL.md +++ b/.claude/skills/add_platform/SKILL.md @@ -67,7 +67,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: - Present available workflows and standalone skills as options - Let user select the starting point diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md index 3839ffbd..639b508f 100644 --- a/.claude/skills/commit/SKILL.md +++ b/.claude/skills/commit/SKILL.md @@ -63,7 +63,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: - Present available workflows and standalone skills as options - Let user select the starting point diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index 83d1bea8..e14f0cb7 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -61,7 +61,7 @@ Guide the user through defining a job specification by asking structured questio ### Key Guidelines -- **Ask structured questions** using the AskUserQuestion tool +- **Use `AskUserQuestion` tool for all questions** - Never output questions as plain text. Always use the AskUserQuestion tool to gather user input with structured options. Ask questions one at a time, wait for the response, then ask the next. - **Work products go in main repo**, not `.deepwork/` (for discoverability) - **Use dates in paths** for periodic outputs that accumulate - **Use `_dataroom` folders** for supporting materials diff --git a/.claude/skills/deepwork_jobs/SKILL.md b/.claude/skills/deepwork_jobs/SKILL.md index ec2526f5..5898f46c 100644 --- a/.claude/skills/deepwork_jobs/SKILL.md +++ b/.claude/skills/deepwork_jobs/SKILL.md @@ -68,7 +68,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: - Present available workflows and standalone skills as options - Let user select the starting point diff --git a/.claude/skills/deepwork_rules.define/SKILL.md b/.claude/skills/deepwork_rules.define/SKILL.md index 6a33878c..bb19f41b 100644 --- a/.claude/skills/deepwork_rules.define/SKILL.md +++ b/.claude/skills/deepwork_rules.define/SKILL.md @@ -26,7 +26,7 @@ Create a new rule file in the `.deepwork/rules/` directory to enforce team guide Guide the user through defining a new rule by asking structured questions. **Do not create the rule without first understanding what they want to enforce.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. ### Step 1: Understand the Rule Purpose diff --git a/.claude/skills/deepwork_rules/SKILL.md b/.claude/skills/deepwork_rules/SKILL.md index 3de565a9..51d0ad10 100644 --- a/.claude/skills/deepwork_rules/SKILL.md +++ b/.claude/skills/deepwork_rules/SKILL.md @@ -67,7 +67,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: - Present available steps as numbered options - Let user select the starting point diff --git a/.claude/skills/manual_tests/SKILL.md b/.claude/skills/manual_tests/SKILL.md index 59b53adc..5806bdad 100644 --- a/.claude/skills/manual_tests/SKILL.md +++ b/.claude/skills/manual_tests/SKILL.md @@ -86,7 +86,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: - Present available workflows and standalone skills as options - Let user select the starting point diff --git a/.claude/skills/update/SKILL.md b/.claude/skills/update/SKILL.md index e63bd476..8571c169 100644 --- a/.claude/skills/update/SKILL.md +++ b/.claude/skills/update/SKILL.md @@ -57,7 +57,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: - Present available steps as numbered options - Let user select the starting point diff --git a/.deepwork/experts/deepwork_jobs/topics/step_instructions.md b/.deepwork/experts/deepwork_jobs/topics/step_instructions.md index 0c45b0d9..eccaf0c2 100644 --- a/.deepwork/experts/deepwork_jobs/topics/step_instructions.md +++ b/.deepwork/experts/deepwork_jobs/topics/step_instructions.md @@ -71,7 +71,7 @@ Before proceeding, gather the following from the user: - **market_segment**: Target market for analysis - **product_category**: Specific product/service category -Use the AskUserQuestion tool to collect these inputs. +Ask questions one at a time and wait for responses. ``` ### 4. Output Format @@ -111,16 +111,16 @@ Define how to verify the step is complete: ### "Ask structured questions" -When gathering user input, always use this phrase: +When gathering user input, use this phrase and ask questions one at a time: ```markdown -Ask structured questions to understand the user's requirements: -1. What is your target market? -2. Who are your main competitors? +Ask structured questions to understand the user's requirements. +Start with: What is your target market? ``` -This phrase triggers the AskUserQuestion tool which provides a better -user experience with clear options. +**Important**: Present one question, wait for the response, then ask the next. +Do not output all questions as a numbered list - this results in poor UX +where the user must scroll through and answer multiple questions at once. ### "Use the Skill tool to invoke" diff --git a/.deepwork/jobs/deepwork_jobs/AGENTS.md b/.deepwork/jobs/deepwork_jobs/AGENTS.md index 6d97d0e5..be54401a 100644 --- a/.deepwork/jobs/deepwork_jobs/AGENTS.md +++ b/.deepwork/jobs/deepwork_jobs/AGENTS.md @@ -54,7 +54,37 @@ deepwork_jobs/ - Bump minor version (0.x.0) for new features or structural changes - Always update changelog when bumping version +## Learnings + +### AskUserQuestion Tool Does Not Exist (2026-02-01) + +**Issue**: The step instructions and expert documentation referenced a tool called +`AskUserQuestion` that does not exist in Claude Code's toolset. + +**Symptom**: When running the define step, the agent would output all questions as +a plain text list instead of asking them interactively one at a time. + +**Root Cause**: The phrase "ask structured questions" was documented as triggering +the `AskUserQuestion` tool, but this was aspirational - the tool was never +implemented in Claude Code. + +**Fix Applied**: +- Removed all references to `AskUserQuestion` tool +- Updated instructions to say "ask questions one at a time" +- Clarified that questions should be presented individually with waits for responses + +**Files Changed**: +- `src/deepwork/standard_jobs/deepwork_jobs/steps/define.md` +- `src/deepwork/standard_jobs/deepwork_rules/steps/define.md` +- `src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md` +- `library/jobs/spec_driven_development/steps/*.md` (multiple files) + +**Lesson**: Do not reference tools in instructions unless they actually exist. +When specifying interactive behavior, be explicit about the expected pattern +(one question at a time, wait for response) rather than referencing hypothetical +tooling. + ## Last Updated -- Date: 2026-01-15 -- From conversation about: Adding make_new_job.sh script and templates directory +- Date: 2026-02-01 +- From conversation about: Learning why define step output questions as plain text diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index a9a6cd73..0e366fd8 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -39,7 +39,7 @@ Guide the user through defining a job specification by asking structured questio ### Key Guidelines -- **Ask structured questions** using the AskUserQuestion tool +- **Use `AskUserQuestion` tool for all questions** - Never output questions as plain text. Always use the AskUserQuestion tool to gather user input with structured options. Ask questions one at a time, wait for the response, then ask the next. - **Work products go in main repo**, not `.deepwork/` (for discoverability) - **Use dates in paths** for periodic outputs that accumulate - **Use `_dataroom` folders** for supporting materials diff --git a/.deepwork/jobs/deepwork_rules/steps/define.md b/.deepwork/jobs/deepwork_rules/steps/define.md index 1e38a5e6..626096dd 100644 --- a/.deepwork/jobs/deepwork_rules/steps/define.md +++ b/.deepwork/jobs/deepwork_rules/steps/define.md @@ -8,7 +8,7 @@ Create a new rule file in the `.deepwork/rules/` directory to enforce team guide Guide the user through defining a new rule by asking structured questions. **Do not create the rule without first understanding what they want to enforce.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. ### Step 1: Understand the Rule Purpose diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 8c6ec898..82265477 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -59,7 +59,7 @@ Guide the user through defining a job specification by asking structured questio ### Key Guidelines -- **Ask structured questions** using the AskUserQuestion tool +- **Use `AskUserQuestion` tool for all questions** - Never output questions as plain text. Always use the AskUserQuestion tool to gather user input with structured options. Ask questions one at a time, wait for the response, then ask the next. - **Work products go in main repo**, not `.deepwork/` (for discoverability) - **Use dates in paths** for periodic outputs that accumulate - **Use `_dataroom` folders** for supporting materials diff --git a/.gemini/skills/deepwork_rules/define.toml b/.gemini/skills/deepwork_rules/define.toml index 980ad931..6e4fd3b0 100644 --- a/.gemini/skills/deepwork_rules/define.toml +++ b/.gemini/skills/deepwork_rules/define.toml @@ -28,7 +28,7 @@ Create a new rule file in the `.deepwork/rules/` directory to enforce team guide Guide the user through defining a new rule by asking structured questions. **Do not create the rule without first understanding what they want to enforce.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. ### Step 1: Understand the Rule Purpose diff --git a/library/jobs/spec_driven_development/steps/clarify.md b/library/jobs/spec_driven_development/steps/clarify.md index 5d8d53da..379defb5 100644 --- a/library/jobs/spec_driven_development/steps/clarify.md +++ b/library/jobs/spec_driven_development/steps/clarify.md @@ -8,7 +8,7 @@ Resolve ambiguities, fill gaps, and validate completeness of the specification t Review the existing specification, identify underspecified areas, and ask structured questions to resolve them. Update the spec.md with clarifications. -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. **Critical**: This step refines requirements, not implementation. Do not add code examples or technical solutions. Keep clarifications focused on user needs, acceptance criteria, and behavior - not how things will be coded. diff --git a/library/jobs/spec_driven_development/steps/constitution.md b/library/jobs/spec_driven_development/steps/constitution.md index 11ab7c70..21c8933e 100644 --- a/library/jobs/spec_driven_development/steps/constitution.md +++ b/library/jobs/spec_driven_development/steps/constitution.md @@ -8,7 +8,7 @@ Create a foundational governance document (`constitution.md`) that establishes p Guide the user through defining their project's constitution by asking structured questions about their development priorities, quality standards, and governance preferences. -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. **Critical**: This step captures principles and standards, not implementation code. The constitution describes what technologies and patterns to use, not how to code them. Do not include code examples - those belong only in the implement step. diff --git a/library/jobs/spec_driven_development/steps/plan.md b/library/jobs/spec_driven_development/steps/plan.md index 1d4c6b6e..4aca4e93 100644 --- a/library/jobs/spec_driven_development/steps/plan.md +++ b/library/jobs/spec_driven_development/steps/plan.md @@ -8,7 +8,7 @@ Create a comprehensive technical implementation plan that defines architecture, Analyze the clarified specification and create detailed technical planning documents that will guide implementation. -**Important**: Use the AskUserQuestion tool to ask structured questions when technology choices need user input. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. **Critical**: This step produces planning documents, NOT implementation code. Do not write actual code - that happens in the implement step. You may include: - API contracts (endpoints, request/response schemas) diff --git a/library/jobs/spec_driven_development/steps/specify.md b/library/jobs/spec_driven_development/steps/specify.md index 6cb0a597..ad24cd55 100644 --- a/library/jobs/spec_driven_development/steps/specify.md +++ b/library/jobs/spec_driven_development/steps/specify.md @@ -8,7 +8,7 @@ Create a functional specification (`spec.md`) that defines what the feature shou Guide the user through creating a comprehensive specification by asking structured questions about their feature requirements, user needs, and success criteria. -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. **Key Principle**: This step focuses entirely on the **"what"** and **"why"** - never the **"how"**. Technology choices and implementation details belong in the planning step. @@ -212,10 +212,7 @@ User: Users need accounts to save their preferences and access their data across Claude: That makes sense. Who are the primary users of this authentication system? -[Uses AskUserQuestion with options: New users signing up, Returning users logging in, -Admins managing users, All of the above] - -User: All of the above +User: New users signing up, returning users logging in, and admins managing users. Claude: Let's create user stories for each. Starting with new users signing up: diff --git a/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md b/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md index 0c45b0d9..eccaf0c2 100644 --- a/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md +++ b/src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md @@ -71,7 +71,7 @@ Before proceeding, gather the following from the user: - **market_segment**: Target market for analysis - **product_category**: Specific product/service category -Use the AskUserQuestion tool to collect these inputs. +Ask questions one at a time and wait for responses. ``` ### 4. Output Format @@ -111,16 +111,16 @@ Define how to verify the step is complete: ### "Ask structured questions" -When gathering user input, always use this phrase: +When gathering user input, use this phrase and ask questions one at a time: ```markdown -Ask structured questions to understand the user's requirements: -1. What is your target market? -2. Who are your main competitors? +Ask structured questions to understand the user's requirements. +Start with: What is your target market? ``` -This phrase triggers the AskUserQuestion tool which provides a better -user experience with clear options. +**Important**: Present one question, wait for the response, then ask the next. +Do not output all questions as a numbered list - this results in poor UX +where the user must scroll through and answer multiple questions at once. ### "Use the Skill tool to invoke" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 6b806bc9..4343cbda 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -48,7 +48,6 @@ steps: name: "Define Job Specification" description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." instructions_file: steps/define.md - agent: deepwork-jobs inputs: - name: job_purpose description: "What complex task or workflow are you trying to accomplish?" @@ -56,12 +55,10 @@ steps: - file: job.yml doc_spec: .deepwork/doc_specs/job_spec.md dependencies: [] - - id: review_job_spec name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." instructions_file: steps/review_job_spec.md - agent: deepwork-jobs inputs: - file: job.yml from_step: define @@ -70,12 +67,16 @@ steps: doc_spec: .deepwork/doc_specs/job_spec.md dependencies: - define + quality_criteria: + - "**Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review?" + - "**All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria?" + - "**Findings Addressed**: Were all failed criteria addressed by the main agent?" + - "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?" - id: implement name: "Implement Job Steps" description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." instructions_file: steps/implement.md - agent: deepwork-jobs inputs: - file: job.yml from_step: review_job_spec @@ -83,12 +84,21 @@ steps: - steps/ dependencies: - review_job_spec + quality_criteria: + - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?" + - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?" + - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?" + - "**Output Examples**: Does each instruction file show what good output looks like?" + - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?" + - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?" + - "**Sync Complete**: Has `deepwork sync` been run successfully?" + - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?" + - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful." - id: learn name: "Learn from Job Execution" description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." instructions_file: steps/learn.md - agent: deepwork-jobs exposed: true inputs: - name: job_name @@ -96,3 +106,16 @@ steps: outputs: - AGENTS.md dependencies: [] + quality_criteria: + - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?" + - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?" + - "**Instructions Improved**: Were job instructions updated to address identified issues?" + - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?" + - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?" + - "**doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?" + - "**doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?" + - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?" + - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?" + - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?" + - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?" + - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index a9a6cd73..31de7440 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -2,51 +2,457 @@ ## Objective -Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. +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 structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. +Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** -### Process +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. -1. **Understand the job purpose** - - Ask structured questions about the overall goal, domain, and frequency - - Understand what success looks like and who the audience is - - Identify the major phases of the workflow +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`). -2. **Detect document-oriented workflows** - - Look for patterns: "report", "summary", "monthly", "for stakeholders" - - If detected, offer to create a doc spec for consistent quality - - Use `.deepwork/doc_specs/job_spec.md` as a reference example +### Step 1: Understand the Job Purpose -3. **Define each step** - - For each phase, gather: purpose, inputs, outputs, dependencies - - Ask about output file paths and organization - - Consider whether steps need agent delegation +Start by asking structured questions to understand what the user wants to accomplish: -4. **Validate the workflow** - - Summarize the complete workflow - - Check for gaps in inputs/outputs between steps - - Confirm job name, summary, and version +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 1.5: Detect Document-Oriented Workflows + +**Check for document-focused patterns** in the user's description: +- Keywords: "report", "summary", "document", "create", "monthly", "quarterly", "for stakeholders", "for leadership" +- Final deliverable is a specific document (e.g., "AWS spending report", "competitive analysis", "sprint summary") +- Recurring documents with consistent structure + +**If a document-oriented workflow is detected:** + +1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first to ensure consistent quality." + +2. Ask structured questions to understand if they want to: + - Create a doc spec for this document + - Use an existing doc spec (if any exist in `.deepwork/doc_specs/`) + - Skip doc spec and proceed with simple outputs + +### Step 1.6: Define the Doc Spec (if needed) + +When creating a doc spec, gather the following information: + +1. **Document Identity** + - What is the document called? (e.g., "Monthly AWS Spending Report") + - Brief description of its purpose + - Where should these documents be stored? (path patterns like `finance/aws-reports/*.md`) + +2. **Audience and Context** + - Who reads this document? (target audience) + - How often is it produced? (frequency) + +3. **Quality Criteria** (3-5 criteria, each with name and description) + + **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve. + + Examples for a spending report: + - **Visualization**: Must include charts showing spend breakdown by service + - **Variance Analysis**: Must compare current month against previous with percentages + - **Action Items**: Must include recommended cost optimization actions + + **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible. + +4. **Document Structure** + - What sections should it have? + - Any required elements (tables, charts, summaries)? + +### Step 1.7: Create the doc spec File (if needed) + +Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`: + +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure. + +**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files). + +After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output. + +### Step 2: Define Each Step + +For each major phase they mentioned, ask structured questions to gather details: + +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? + - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output + + #### Work Product Storage Guidelines + + **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only. + + **Why this matters**: + - **Version control**: Work products in the main repo are tracked by git and visible in PRs + - **Discoverability**: Team members can find outputs without knowing about DeepWork internals + - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths + - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`) -5. **Create the job specification** - - Run `make_new_job.sh` to create directory structure: - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] + **Good output path patterns**: + ``` + competitive_research/competitors_list.md + competitive_research/acme_corp/research.md + operations/reports/2026-01/spending_analysis.md + docs/api/endpoints.md + ``` + + **Avoid these patterns**: + ``` + .deepwork/outputs/report.md # Hidden in dot-directory + output.md # Too generic, no context + research.md # Unclear which research + temp/draft.md # Transient-sounding paths + ``` + + **Organizing multi-file outputs**: + - Use the job name as a top-level folder when outputs are job-specific + - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/` + - Match existing project conventions when extending a codebase + + **When to include dates in paths**: + - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful. + ``` + operations/reports/2026-01/spending_analysis.md # Monthly report - keep history + hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf # Per-employee quarterly review + ``` + - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files. + ``` + competitive_research/acme_corp/swot.md # Current SWOT - updated over time + docs/architecture/overview.md # Living document + ``` + + **Supporting materials and intermediate outputs**: + - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output + - Name the dataroom folder by replacing the file extension with `_dataroom` ``` - - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` + operations/reports/2026-01/spending_analysis.md # Final output + operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials + raw_data.csv + vendor_breakdown.md + notes.md + ``` + - This keeps supporting materials organized and discoverable without cluttering the main output location + +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? + +6. **Agent Delegation** (optional) + - Should this step be executed by a specific agent type? + - Use the `agent` field when the step should run in a forked context with a specific agent + - When `agent` is set, the generated skill automatically includes `context: fork` + - Available agent types: + - `general-purpose` - Standard agent for multi-step tasks + + ```yaml + steps: + - id: research_step + agent: general-purpose # Delegates to the general-purpose agent + ``` + +**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. + +#### Doc Spec-Aware Output Format + +When a step produces a document with a doc spec reference, use this format in job.yml: + +```yaml +outputs: + - file: reports/monthly_spending.md + doc_spec: .deepwork/doc_specs/monthly_aws_report.md +``` + +The doc spec's quality criteria will automatically be included in the generated skill, ensuring consistent document quality. + +### Capability Considerations + +When defining steps, identify any that require specialized tools: + +**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. + +### Step 3: Validate the Workflow + +After gathering information about all steps: + +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: Define Quality Validation (Stop Hooks) + +For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. + +**Ask structured questions about quality validation:** +- "Are there specific quality criteria that must be met for this step?" +- "Would you like the agent to validate its work before completing?" +- "What would make you send the work back for revision?" + +**Stop hooks are particularly valuable for:** +- Steps with complex outputs that need multiple checks +- Steps where quality is critical (final deliverables) +- Steps with subjective quality criteria that benefit from AI self-review + +**Three types of stop hooks are supported:** + +1. **Inline Prompt** (`prompt`) - Best for simple quality criteria + ```yaml + stop_hooks: + - prompt: | + Verify the output meets these criteria: + 1. Contains at least 5 competitors + 2. Each competitor has a description + 3. Selection rationale is clear + ``` + +2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria + ```yaml + stop_hooks: + - prompt_file: hooks/quality_check.md + ``` + +3. **Script** (`script`) - For programmatic validation (tests, linting) + ```yaml + stop_hooks: + - script: hooks/run_tests.sh + ``` + +**Multiple hooks can be combined:** +```yaml +stop_hooks: + - script: hooks/lint_output.sh + - prompt: "Verify the content is comprehensive and well-organized" +``` + +**Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). + +### Step 5: Create the Job Directory and Specification + +Only after you have complete understanding, create the job directory and `job.yml` file: + +**First, create the directory structure** using the `make_new_job.sh` script: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - For step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - For example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) + +**Doc Spec**: See `.deepwork/doc_specs/job_spec.md` for the complete specification with quality criteria. + +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. + +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. + +**Important**: +- Use lowercase with underscores for job name and step IDs +- Ensure file inputs reference steps in dependencies +- 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 +- Include a `changelog` section with an initial entry for version 1.0.0 + +## 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 in the project root, or in a subdirectory like `research/` or `data/`? + +User: Just call it `competitors_list.md` in the project root. + +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/jobs/competitive_research/job.yml with the complete spec] + +✓ Job specification created! + +**File created:** +- .deepwork/jobs/competitive_research/job.yml + +**Next step:** +Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria. +``` + +## Important Guidelines + +1. **Focus on specification only** - Don't create instruction files yet +2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool +3. **Rich context in description** - This helps with future refinement +4. **Validate understanding** - Summarize and confirm before creating +5. **Use examples** - Help users understand what good specifications look like +6. **Understand file organization** - Always ask structured questions about 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 -### Key Guidelines +The complete YAML specification file (example shown in Step 5 above). -- **Ask structured questions** using the AskUserQuestion tool -- **Work products go in main repo**, not `.deepwork/` (for discoverability) -- **Use dates in paths** for periodic outputs that accumulate -- **Use `_dataroom` folders** for supporting materials -- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` +**Location**: `.deepwork/jobs/[job_name]/job.yml` -## Output +(Where `[job_name]` is the name of the new job being created) -Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. +After creating the file: +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.review_job_spec` next -After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index 214338ea..749c8c6f 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -2,62 +2,232 @@ ## Objective -Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step. ## Task -Read the job.yml and create comprehensive instruction files for each step. +Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. -### Process +### Step 1: Create Directory Structure Using Script -1. **Create directory structure** (if needed) - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` +Run the `make_new_job.sh` script to create the standard directory structure: -2. **Read and validate the specification** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Extract job name, description, and step details - - Understand the workflow structure +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) +- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -3. **Generate step instruction files** - - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step - - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference - - Each file must include: Objective, Task, Process, Output Format, Quality Criteria +**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: +```bash +mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates +touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep +``` -4. **Sync skills** - ```bash - deepwork sync - ``` +### Step 2: Read and Validate the Specification -5. **Consider rules for the new job** - - Think about whether rules would help maintain quality - - If relevant, explain and offer to run `/deepwork_rules.define` +1. **Locate the job.yml file** + - Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec step + - Parse the YAML content -### Instruction File Guidelines +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 -- **Be specific** - tailor to each step's purpose, not generic advice -- **Provide examples** - show what good output looks like -- **Include quality criteria** - how to verify the step is complete -- **Use "ask structured questions"** - for steps that gather user input -- **Align with hooks** - if step has hooks, match the validation criteria +### Step 3: Generate Step Instruction Files -### Templates Available +For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`. +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. + +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. + +**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** - `job.yml.template` - Job specification structure - `step_instruction.md.template` - Step instruction file structure - `agents.md.template` - AGENTS.md file structure -- Examples: `job.yml.example`, `step_instruction.md.example` +- `job.yml.example` - Complete job specification example +- `step_instruction.md.example` - Complete step instruction example -## Completion Checklist +**Guidelines for generating instructions:** -- [ ] All step instruction files created (not stubs) -- [ ] Instructions are specific and actionable -- [ ] Output examples provided -- [ ] Quality criteria defined -- [ ] `deepwork sync` executed successfully -- [ ] Rules considered (suggest if genuinely helpful) +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 +6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks +7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" + +### Handling Stop Hooks + +If a step in the job.yml has `stop_hooks` defined, the generated instruction file should: + +1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the stop hooks will validate +2. **Be explicit about success** - Help the agent understand when the step is truly complete +3. **Include the promise pattern** - Mention that `✓ Quality Criteria Met` should be included when criteria are met + +**Example: If the job.yml has:** +```yaml +- id: research_competitors + name: "Research Competitors" + stop_hooks: + - prompt: | + Verify the research meets criteria: + 1. Each competitor has at least 3 data points + 2. Sources are cited + 3. Information is current (within last year) +``` + +**The instruction file should include:** +```markdown +## Quality Criteria + +- Each competitor has at least 3 distinct data points +- All information is sourced with citations +- Data is current (from within the last year) +- When all criteria are met, include `✓ Quality Criteria Met` in your response +``` + +This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. + +### Using Supplementary Reference Files + +Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. + +See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. + +### Step 4: Verify job.yml Location + +Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it. + +### Step 5: Sync Skills + +Run `deepwork sync` to generate the skills for this job: + +```bash +deepwork sync +``` + +This will: +- Parse the job definition +- Generate skills for each step +- Make the skills available in `.claude/skills/` (or appropriate platform directory) + +### Step 6: Consider Rules for the New Job -## Output +After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain. -Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. +**What are rules?** + +Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure: +- Documentation stays in sync with code +- Team guidelines are followed +- Architectural decisions are respected +- Quality standards are maintained + +**When to suggest rules:** + +Think about the job you just implemented and ask: +- Does this job produce outputs that other files depend on? +- Are there documentation files that should be updated when this job's outputs change? +- Are there quality checks or reviews that should happen when certain files in this domain change? +- Could changes to the job's output files impact other parts of the project? + +**Examples of rules that might make sense:** + +| Job Type | Potential Rule | +|----------|----------------| +| API Design | "Update API docs when endpoint definitions change" | +| Database Schema | "Review migrations when schema files change" | +| Competitive Research | "Update strategy docs when competitor analysis changes" | +| Feature Development | "Update changelog when feature files change" | +| Configuration Management | "Update install guide when config files change" | + +**How to offer rule creation:** + +If you identify one or more rules that would benefit the user, explain: +1. **What the rule would do** - What triggers it and what action it prompts +2. **Why it would help** - How it prevents common mistakes or keeps things in sync +3. **What files it would watch** - The trigger patterns + +Then ask the user: + +> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up." + +If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule. + +**Example dialogue:** + +``` +Based on the competitive_research job you just created, I noticed that when +competitor analysis files change, it would be helpful to remind you to update +your strategy documentation. + +I'd suggest a rule like: +- **Name**: "Update strategy when competitor analysis changes" +- **Trigger**: `**/positioning_report.md` +- **Action**: Prompt to review and update `docs/strategy.md` + +Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up. +``` + +**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense. + +## Example Implementation + +For a complete worked example showing a job.yml and corresponding step instruction file, see: +- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` +- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` + +## Important Guidelines + +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) +- No file system errors + +## 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 +- [ ] `deepwork sync` executed successfully +- [ ] Skills generated in platform directory +- [ ] Considered whether rules would benefit this job (Step 6) +- [ ] If rules suggested, offered to run `/deepwork_rules.define` + +## 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 +- Steps with user inputs explicitly use "ask structured questions" phrasing +- Sync completed successfully +- Skills available for use +- Thoughtfully considered relevant rules for the job domain diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index f7175cb4..bfb393a5 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -2,68 +2,354 @@ ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. +Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. ## Task -Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** - Update job instruction files -- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic +Analyze the conversation history to extract learnings and improvements, then apply them appropriately: +- **Generalizable learnings** → Update job instruction files +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic -### Process +### Step 1: Analyze Conversation for Job Executions -1. **Analyze conversation for job executions** - - Scan for DeepWork slash commands (`/job_name.step_id`) +1. **Scan the conversation** for DeepWork slash commands that were run + - Look for patterns like `/job_name.step_id` - Identify which jobs and steps were executed - - If unclear, run `git diff` to see where changes were made - -2. **Identify issues and patterns** - - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs - - **Inefficiency**: extra iterations, repeated information, missing context - - **Errors**: failed validations, edge cases, quality criteria issues - - **Successes**: what worked well, efficient approaches - -3. **Classify each learning** - - **Generalizable**: would help ANY future run (update instructions) - - **Doc spec-related**: improves document quality criteria (update doc specs) - - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) - -4. **Update job instructions** (generalizable learnings) - - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep concise - avoid redundancy - - Extract shared content to `steps/shared/` if needed - -5. **Update doc specs** (if applicable) - - Edit `.deepwork/doc_specs/[doc_spec_name].md` - - Update quality criteria or document structure - -6. **Create/update AGENTS.md** (bespoke learnings) - - Place in deepest common folder for the topic - - Use file references instead of duplicating content + - Note the order of execution + +2. **Identify the target folder** + - This should be the deepest common folder that would contain all work on the topic in the future + - Should be clear from conversation history where work was done + - If unclear, run `git diff` to see where changes were made on the branch + +3. **If no job was specified**, ask the user: + - "Which DeepWork job would you like me to learn from?" + - List available jobs from `.deepwork/jobs/` + +### Step 2: Identify Points of Confusion and Inefficiency + +Review the conversation for: + +1. **Confusion signals** + - Questions the agent asked that shouldn't have been necessary + - Misunderstandings about what a step required + - Incorrect outputs that needed correction + - Ambiguous instructions that led to wrong interpretations + +2. **Inefficiency signals** + - Extra steps or iterations that were needed + - Information that had to be repeated + - Context that was missing from instructions + - Dependencies that weren't clear + +3. **Error patterns** + - Failed validations and why they failed + - Quality criteria that were misunderstood + - Edge cases that weren't handled + +4. **Success patterns** + - What worked particularly well + - Efficient approaches worth preserving + - Good examples that could be added to instructions + +### Step 3: Classify Learnings + +For each learning identified, determine if it is: + +**Generalizable** (should improve instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions in instructions +- Adds helpful examples or context +- Examples: + - "Step instructions should mention that X format is required" + - "Quality criteria should include checking for Y" + - "Add example of correct output format" + +**doc spec-Related** (should improve doc spec files): +- Improvements to document quality criteria +- Changes to document structure or format +- Updated audience or frequency information +- Examples: + - "The report should include a summary table" + - "Quality criterion 'Visualization' needs clearer requirements" + - "Documents need a section for action items" + +**Bespoke** (should go in AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions or structure +- References specific files or paths +- Would not apply to other uses of this job +- Examples: + - "In this codebase, API endpoints are in `src/api/`" + - "This project uses camelCase for function names" + - "The main config file is at `config/settings.yml`" + +### Step 3.5: Identify doc spec-Related Learnings + +Review the conversation for doc spec-related improvements: + +1. **Quality Criteria Changes** + - Were any quality criteria unclear or insufficient? + - Did the agent repeatedly fail certain criteria? + - Are there new criteria that should be added? + +2. **Document Structure Changes** + - Did the user request different sections? + - Were parts of the document format confusing? + - Should the example document be updated? + +3. **Metadata Updates** + - Has the target audience changed? + - Should frequency or path patterns be updated? + +**Signals for doc spec improvements:** +- User asked for changes to document format +- Repeated validation failures on specific criteria +- Feedback about missing sections or information +- Changes to how documents are organized/stored + +### Step 4: Update Job Instructions (Generalizable Learnings) + +For each generalizable learning: + +1. **Locate the instruction file** + - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` + +2. **Make targeted improvements** + - Add missing context or clarification + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria if needed + +3. **Keep instructions concise** + - Avoid redundancy - don't repeat the same guidance in multiple places + - Be direct - remove verbose explanations that don't add value + - Prefer bullet points over paragraphs where appropriate + +4. **Preserve instruction structure** + - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) + - Add to appropriate sections rather than restructuring + - Maintain consistency with other steps + +5. **Track changes for changelog** + - Note what was changed and why + - Prepare changelog entry for job.yml + +### Step 4b: Extract Shared Content into Referenced Files + +Review all instruction files for the job and identify content that: +- Appears in multiple step instructions (duplicated) +- Is lengthy and could be extracted for clarity +- Would benefit from being maintained in one place + +**Extract to shared files:** + +1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` + - `conventions.md` - Coding/formatting conventions used across steps + - `examples.md` - Common examples referenced by multiple steps + - `schemas.md` - Data structures or formats used throughout + +2. **Reference from instructions** using markdown includes or explicit references: + ```markdown + ## Conventions + + Follow the conventions defined in `shared/conventions.md`. + ``` + +3. **Benefits of extraction:** + - Single source of truth - update once, applies everywhere + - Shorter instruction files - easier to read and maintain + - Consistent guidance across steps + +### Step 4.5: Update doc spec Files (doc spec-Related Learnings) + +If doc spec-related learnings were identified: + +1. **Locate the doc spec file** + - Find doc spec references in job.yml outputs (look for `doc_spec: .deepwork/doc_specs/[doc_spec_name].md`) + - doc spec files are at `.deepwork/doc_specs/[doc_spec_name].md` + +2. **Update quality_criteria array** + - Add new criteria with name and description + - Modify existing criteria descriptions for clarity + - Remove criteria that are no longer relevant + +3. **Update example document** + - Modify the markdown body to reflect structure changes + - Ensure the example matches updated criteria + +4. **Update metadata as needed** + - target_audience: If audience has changed + - frequency: If production cadence has changed + - path_patterns: If storage location has changed + +**Example doc spec update:** +```yaml +# Before +quality_criteria: + - name: Visualization + description: Include charts + +# After +quality_criteria: + - name: Visualization + description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend +``` + +### Step 5: Create/Update AGENTS.md (Bespoke Learnings) + +The AGENTS.md file captures project-specific knowledge that helps future agent runs. + +1. **Determine the correct location** + - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future + - This ensures the knowledge is available when working in that context + - If uncertain, place at the project root + +2. **Use file references where possible** + - Instead of duplicating information, reference source files + - This keeps AGENTS.md in sync as the codebase evolves - Pattern: "See `path/to/file.ext` for [description]" -7. **Update version and sync** - - Bump version in job.yml (patch for instructions, minor for criteria) - - Add changelog entry - - Run `deepwork sync` if instructions were modified +3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. + +4. **Writing entries** + - Be concise but specific + - Always prefer file references over inline content + - Use line numbers when referencing specific code: `file.ext:42` + - Group related learnings together + +### Step 6: Update Job Version and Changelog -### File Reference Patterns +If instruction files were modified: + +1. **Bump version in job.yml** + - Patch version (0.0.x) for instruction improvements + - Minor version (0.x.0) if quality criteria changed + +2. **Add changelog entry** + ```yaml + - version: "[new_version]" + changes: "Improved [step] instructions based on execution learnings: [brief description]" + ``` + +### Step 7: Sync Skills + +**Run deepwork sync** (if instructions were modified) +```bash +deepwork sync +``` + +## File Reference Patterns + +When adding entries to AGENTS.md, prefer these patterns: **Good (references)**: ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. - Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` ``` **Avoid (duplicating)**: ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } +- Error handling should use try/catch with custom error classes +- Configuration requires these fields: name, version, ... +``` + +## Quality Criteria + +- Conversation has been analyzed for job executions +- Points of confusion and inefficiency are identified +- Learnings are correctly classified (generalizable vs bespoke) +- Job instructions updated for generalizable improvements +- Instructions are concise - no redundancy or unnecessary verbosity +- Shared/lengthy content extracted into referenced files where appropriate +- AGENTS.md created/updated with bespoke learnings +- File references used instead of duplicating content +- AGENTS.md is in the correct folder (the deepest common folder for the topic) +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.learn + +Claude: I'll analyze this conversation for learnings from DeepWork job executions. + +**Conversation Analysis** + +I found the following job executions: +1. `/competitive_research.identify_competitors` - Completed +2. `/competitive_research.research_competitors` - Completed with 2 iterations +3. `/competitive_research.comparative_analysis` - Completed + +**Identified Issues** + +1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. + +2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. + +**Classification** + +- Generalizable: Add pricing to research requirements in instructions +- Bespoke: This project focuses on B2B SaaS in the HR tech space + +**Actions Taken** + +1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: + - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements + - Added note about carrying forward industry context from previous step + +2. Created `./competitive_research_output/AGENTS.md`: + ```markdown + # Project Context for Competitive Research + + ## Job-Specific Context + + ### competitive_research + + #### Industry Focus + - Domain: B2B SaaS, HR Technology sector + - See `identify_competitors_output.md` for market definition + + #### Competitors Identified + - Reference: `competitor_list.md` for full details + + ## Last Updated + - Date: 2024-01-15 + - From conversation about: Initial competitive analysis run + ``` + +3. Updated job.yml version to 1.0.1 with changelog entry + +4. Ran `deepwork sync` + +**Summary** + +Updated job instructions and created AGENTS.md with bespoke learnings. ``` -## Output +## Handling Edge Cases + +**No job executions found**: +- Ask user which job they'd like to analyze +- Or offer to review available jobs + +**Multiple jobs executed**: +- Analyze each job separately +- Create separate AGENTS.md entries or files as appropriate + +**AGENTS.md already exists**: +- Read existing content +- Append new learnings to appropriate sections +- Update "Last Updated" section -- Updated instruction files (generalizable improvements) -- Updated doc specs (if applicable) -- AGENTS.md in the correct working folder (bespoke learnings) +**No issues found**: +- Document what worked well +- Consider if any successful patterns should be added to instructions as examples -Include `Quality Criteria Met` when complete. +**Sensitive information**: +- Never include secrets, credentials, or PII in AGENTS.md +- Reference config files instead of including values diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md index 621cfa6b..fcc0ae9c 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md @@ -6,48 +6,203 @@ Review the `job.yml` created in the define step against the doc spec quality cri ## Why This Step Exists -The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. +The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. +Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass. -### Process +### Step 1: Read the Job Specification -1. **Read the files** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Read `.deepwork/doc_specs/job_spec.md` for reference +Read the `job.yml` file created in the define step: -2. **Spawn review sub-agent** - - Use Task tool with `subagent_type: general-purpose` and `model: haiku` - - Include the full job.yml content and all 9 quality criteria in the prompt - - Request PASS/FAIL for each criterion with specific issues if failed +``` +.deepwork/jobs/[job_name]/job.yml +``` -3. **Fix failed criteria** - - Edit job.yml to address each failed criterion - - Common fixes: shorten summary, add changelog, fix dependencies +Also read the doc spec for reference: -4. **Re-run review if needed** - - Spawn a new sub-agent with updated content - - Repeat until all 9 criteria pass +``` +.deepwork/doc_specs/job_spec.md +``` -5. **Confirm completion** - - Announce "All 9 doc spec quality criteria pass" - - Include `Quality Criteria Met` - - Guide to next step: `/deepwork_jobs.implement` +### Step 2: Spawn Review Sub-Agent -### The 9 Quality Criteria +Use the Task tool to spawn a sub-agent that will provide an unbiased review: -1. **Valid Identifier**: lowercase with underscores, no spaces -2. **Semantic Version**: X.Y.Z format -3. **Concise Summary**: under 200 characters -4. **Rich Description**: multi-line with problem/process/outcome/users -5. **Changelog Present**: array with at least initial version -6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: reference existing steps, no circular refs -8. **Input Consistency**: from_step must be in dependencies -9. **Output Paths**: valid filenames or paths +``` +Task tool parameters: +- subagent_type: "general-purpose" +- model: "haiku" +- description: "Review job.yml against doc spec" +- prompt: [see below] +``` + +**Sub-agent prompt template:** + +``` +Review this job.yml against the following 9 quality criteria from the doc spec. + +For each criterion, respond with: +- PASS or FAIL +- If FAIL: specific issue and suggested fix + +## job.yml Content + +[paste the full job.yml content here] + +## Quality Criteria + +1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`) + +2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`) + +3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes + +4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users + +5. **Changelog Present**: Must include a changelog array with at least the initial version entry + +6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array + +7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references + +8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array + +9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`) + +## Response Format + +Respond with a structured evaluation: + +### Overall: [X/9 PASS] + +### Criterion Results + +1. Valid Identifier: [PASS/FAIL] + [If FAIL: Issue and fix] + +2. Semantic Version: [PASS/FAIL] + [If FAIL: Issue and fix] + +[... continue for all 9 criteria ...] + +### Summary of Required Fixes + +[List any fixes needed, or "No fixes required - all criteria pass"] +``` + +### Step 3: Review Sub-Agent Findings + +Parse the sub-agent's response: + +1. **Count passing criteria** - How many of the 9 criteria passed? +2. **Identify failures** - List specific criteria that failed +3. **Note suggested fixes** - What changes does the sub-agent recommend? + +### Step 4: Fix Failed Criteria + +For each failed criterion, edit the job.yml to address the issue: + +**Common fixes by criterion:** + +| Criterion | Common Issue | Fix | +|-----------|-------------|-----| +| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | +| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format | +| Concise Summary | Too long or vague | Shorten to <200 chars, be specific | +| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users | +| Changelog Present | Missing changelog | Add `changelog:` with initial version entry | +| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies | +| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies | +| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array | +| Output Paths | Invalid characters or format | Use valid filename/path format | + +### Step 5: Re-Run Review (If Needed) + +If any criteria failed: + +1. **Spawn a new sub-agent** with the updated job.yml content +2. **Review the new findings** +3. **Fix any remaining issues** +4. **Repeat until all 9 criteria pass** + +### Step 6: Confirm Completion + +When all 9 criteria pass: + +1. **Announce success**: "All 9 doc spec quality criteria pass." +2. **List what was validated**: + - Valid Identifier + - Semantic Version + - Concise Summary + - Rich Description + - Changelog Present + - Complete Steps + - Valid Dependencies + - Input Consistency + - Output Paths +3. **Include the promise**: `Quality Criteria Met` +4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files." + +## Example Review Cycle + +``` +Claude: Let me review the job.yml against the doc spec quality criteria. + +[Spawns sub-agent with haiku model] + +Sub-agent response: +### Overall: 7/9 PASS + +### Criterion Results +1. Valid Identifier: PASS +2. Semantic Version: PASS +3. Concise Summary: FAIL + Issue: Summary is 245 characters, exceeds 200 char limit + Fix: Shorten to "Competitive analysis workflow for product positioning" +4. Rich Description: PASS +5. Changelog Present: FAIL + Issue: No changelog array present + Fix: Add changelog with initial version entry +6. Complete Steps: PASS +7. Valid Dependencies: PASS +8. Input Consistency: PASS +9. Output Paths: PASS + +### Summary of Required Fixes +1. Shorten summary to under 200 characters +2. Add changelog array with initial version + +Claude: I found 2 issues. Let me fix them. + +[Edits job.yml to shorten summary and add changelog] + +Claude: Let me verify the fixes with another review. + +[Spawns new sub-agent] + +Sub-agent response: +### Overall: 9/9 PASS + +### Summary of Required Fixes +No fixes required - all criteria pass + +Claude: All 9 doc spec quality criteria pass. + +Quality Criteria Met + +**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files. +``` + +## Quality Criteria + +- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review) +- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec +- **Findings Addressed**: All failed criteria were fixed by the main agent +- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed +- **Promise Included**: The response includes `Quality Criteria Met` when complete ## Output -The validated `job.yml` file that passes all quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria. diff --git a/src/deepwork/standard_jobs/deepwork_rules/steps/define.md b/src/deepwork/standard_jobs/deepwork_rules/steps/define.md index 1e38a5e6..626096dd 100644 --- a/src/deepwork/standard_jobs/deepwork_rules/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_rules/steps/define.md @@ -8,7 +8,7 @@ Create a new rule file in the `.deepwork/rules/` directory to enforce team guide Guide the user through defining a new rule by asking structured questions. **Do not create the rule without first understanding what they want to enforce.** -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. +**Important**: Ask questions one at a time - present a question, wait for the user's response, then ask the next. Do not output all questions as a list. ### Step 1: Understand the Rule Purpose diff --git a/src/deepwork/templates/claude/skill-job-meta.md.jinja b/src/deepwork/templates/claude/skill-job-meta.md.jinja index ea258a87..0e0a1603 100644 --- a/src/deepwork/templates/claude/skill-job-meta.md.jinja +++ b/src/deepwork/templates/claude/skill-job-meta.md.jinja @@ -127,7 +127,7 @@ After each step completes: ### Handling Ambiguous Intent -If user intent is unclear, use AskUserQuestion to clarify: +If user intent is unclear, ask which option they want: {% if has_workflows %} - Present available workflows and standalone skills as options {% else %} From 94b5ebc0ca3d1198d28e772195af6f283296b3a0 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 1 Feb 2026 10:33:13 -0700 Subject: [PATCH 9/9] deepwork_job improved --- .claude/skills/deepwork_jobs.define/SKILL.md | 115 +++-- .../skills/deepwork_jobs.implement/SKILL.md | 120 +++-- .claude/skills/deepwork_jobs.learn/SKILL.md | 129 +++-- .../deepwork_jobs.review_job_spec/SKILL.md | 91 ++-- .deepwork/jobs/deepwork_jobs/AGENTS.md | 34 +- .deepwork/jobs/deepwork_jobs/job.yml | 12 +- .deepwork/jobs/deepwork_jobs/steps/define.md | 113 +++-- .../jobs/deepwork_jobs/steps/implement.md | 118 +++-- .deepwork/jobs/deepwork_jobs/steps/learn.md | 127 +++-- .../deepwork_jobs/steps/review_job_spec.md | 89 ++-- .gemini/skills/deepwork_jobs/define.toml | 113 +++-- .gemini/skills/deepwork_jobs/implement.toml | 118 +++-- .gemini/skills/deepwork_jobs/learn.toml | 127 +++-- .../skills/deepwork_jobs/review_job_spec.toml | 89 ++-- .../standard_jobs/deepwork_jobs/job.yml | 37 +- .../deepwork_jobs/steps/define.md | 469 +++--------------- .../deepwork_jobs/steps/implement.md | 214 ++------ .../deepwork_jobs/steps/learn.md | 363 +++----------- .../deepwork_jobs/steps/review_job_spec.md | 208 ++------ 19 files changed, 1132 insertions(+), 1554 deletions(-) diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index e14f0cb7..77074616 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -3,7 +3,7 @@ name: deepwork_jobs.define description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." user-invocable: false context: fork -agent: deepwork-jobs +agent: experts --- @@ -24,52 +24,103 @@ agent: deepwork-jobs ## Objective -Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. +Create a `job.yml` specification file that defines a new DeepWork job by understanding the user's workflow requirements through interactive questioning. ## Task Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -### Process +### Phase 1: Understand the Job Purpose -1. **Understand the job purpose** - - Ask structured questions about the overall goal, domain, and frequency - - Understand what success looks like and who the audience is - - Identify the major phases of the workflow +Ask structured questions to understand the workflow: -2. **Detect document-oriented workflows** - - Look for patterns: "report", "summary", "monthly", "for stakeholders" - - If detected, offer to create a doc spec for consistent quality - - Use `.deepwork/doc_specs/job_spec.md` as a reference example +1. **Overall goal** - What complex task are they trying to accomplish? What domain (research, marketing, development, reporting)? -3. **Define each step** - - For each phase, gather: purpose, inputs, outputs, dependencies - - Ask about output file paths and organization - - Consider whether steps need agent delegation +2. **Success criteria** - What's the final deliverable? Who is the audience? What quality matters most? -4. **Validate the workflow** - - Summarize the complete workflow - - Check for gaps in inputs/outputs between steps - - Confirm job name, summary, and version +3. **Major phases** - What are the distinct stages from start to finish? Any dependencies between phases? -5. **Create the job specification** - - Run `make_new_job.sh` to create directory structure: - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` - - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` +### Phase 2: Detect Document-Oriented Workflows -### Key Guidelines +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly", "for stakeholders" +- Final deliverable is a specific document type +- Recurring documents with consistent structure -- **Use `AskUserQuestion` tool for all questions** - Never output questions as plain text. Always use the AskUserQuestion tool to gather user input with structured options. Ask questions one at a time, wait for the response, then ask the next. -- **Work products go in main repo**, not `.deepwork/` (for discoverability) -- **Use dates in paths** for periodic outputs that accumulate -- **Use `_dataroom` folders** for supporting materials -- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` +**If detected**, offer to create a doc spec: +1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first." +2. Ask if they want to create a doc spec, use existing one, or skip + +**If creating a doc spec**, gather: +- Document name and purpose +- Target audience and frequency +- Quality criteria (3-5, focused on the output document itself) +- Document structure (sections, required elements) + +Create at `.deepwork/doc_specs/[doc_spec_name].md`. Reference `.deepwork/doc_specs/job_spec.md` for an example. + +### Phase 3: Define Each Step + +For each major phase, gather: + +1. **Purpose** - What does this step accomplish? What are inputs and outputs? + +2. **Inputs**: + - User-provided parameters (e.g., topic, target audience)? + - Files from previous steps? + +3. **Outputs**: + - What files does this step produce? + - Format (markdown, YAML, JSON)? + - Where to save? (Use meaningful paths like `competitive_research/analysis.md`, not `.deepwork/outputs/`) + - Does this output have a doc spec? + +4. **Dependencies** - Which previous steps must complete first? + +5. **Process** - Key activities? Quality checks needed? + +6. **Agent Delegation** - Should this step run via a specific agent? Use `agent: experts` for domain-specific expertise. + +#### Output Path Guidelines + +- Place outputs in main repo, not dot-directories +- Use job name as top-level folder for job-specific outputs +- Include dates for periodic outputs that accumulate (monthly reports) +- Omit dates for current-state outputs that get updated in place +- Use `_dataroom` folders for supporting materials + +### Phase 4: Validate the Workflow + +After gathering all step information: + +1. **Review the flow** - Summarize the complete workflow, show how outputs feed into next steps +2. **Check for gaps** - Undefined inputs? Unused outputs? Circular dependencies? +3. **Confirm details** - Job name (lowercase_underscores), summary (max 200 chars), description (detailed), version (1.0.0) + +### Phase 5: Create the Job + +Create the directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml`. + +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for structure and `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a complete example. + +**Validation rules**: +- Job name: lowercase, underscores, no spaces +- Version: semantic versioning (1.0.0) +- Summary: under 200 characters +- Step IDs: unique, lowercase with underscores +- Dependencies must reference existing steps +- File inputs with `from_step` must be in dependencies +- At least one output per step ## Output -Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. +**File**: `.deepwork/jobs/[job_name]/job.yml` After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index 009939a9..8dd70c0a 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -3,7 +3,7 @@ name: deepwork_jobs.implement description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." user-invocable: false context: fork -agent: deepwork-jobs +agent: experts --- @@ -28,65 +28,105 @@ Before proceeding, confirm these steps are complete: ## Objective -Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the job.yml and create comprehensive instruction files for each step. +Read the `job.yml` specification and create all necessary files to make the job functional, then sync the commands. -### Process +### Step 1: Create Directory Structure -1. **Create directory structure** (if needed) - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` +Run the `make_new_job.sh` script: -2. **Read and validate the specification** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Extract job name, description, and step details - - Understand the workflow structure +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` -3. **Generate step instruction files** - - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step - - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference - - Each file must include: Objective, Task, Process, Output Format, Quality Criteria +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -4. **Sync skills** - ```bash - deepwork sync - ``` +**Note**: If directory exists from define step, skip or just create missing subdirectories. -5. **Consider rules for the new job** - - Think about whether rules would help maintain quality - - If relevant, explain and offer to run `/deepwork_rules.define` +### Step 2: Read and Validate the Specification -### Instruction File Guidelines +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate: name, version, summary, description, steps are present +3. Check dependencies reference existing steps, no circular dependencies +4. Verify file inputs match dependencies -- **Be specific** - tailor to each step's purpose, not generic advice -- **Provide examples** - show what good output looks like -- **Include quality criteria** - how to verify the step is complete -- **Use "ask structured questions"** - for steps that gather user input -- **Align with hooks** - if step has hooks, match the validation criteria +### Step 3: Generate Step Instruction Files -### Templates Available +For each step in job.yml, create `.deepwork/jobs/[job_name]/steps/[step_id].md`. -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- Examples: `job.yml.example`, `step_instruction.md.example` +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for structure. + +**Guidelines**: + +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to the step's purpose, not generic +3. **Provide examples** - Show what good output looks like +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - Steps with user inputs MUST explicitly tell the agent to "ask structured questions" +6. **Align with hooks** - If step has `stop_hooks`, ensure quality criteria match the hooks + +Each instruction file should include: +- **Objective** - What this step accomplishes +- **Task** - Detailed process +- **Output Format** - Examples of expected outputs +- **Quality Criteria** - How to verify completion + +### Step 4: Verify job.yml Location + +Ensure `job.yml` is at `.deepwork/jobs/[job_name]/job.yml`. + +### Step 5: Sync Skills + +Run: + +```bash +deepwork sync +``` + +This generates skills in `.claude/skills/` (or appropriate platform directory). + +### Step 6: Consider Rules + +After implementing, consider whether **rules** would help this job's domain. + +**What are rules?** Automated guardrails that trigger when certain files change, ensuring: +- Documentation stays in sync +- Team guidelines are followed +- Quality standards are maintained + +**When to suggest rules:** +- Does this job produce outputs that other files depend on? +- Are there docs that should update when outputs change? +- Could changes impact other parts of the project? + +**Examples**: +| Job Type | Potential Rule | +|----------|----------------| +| API Design | "Update API docs when endpoint definitions change" | +| Competitive Research | "Update strategy docs when competitor analysis changes" | +| Feature Development | "Update changelog when feature files change" | + +If you identify helpful rules, explain what they would do and offer: "Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up." + +**Note**: Not every job needs rules. Only suggest when genuinely helpful. ## Completion Checklist +- [ ] job.yml in correct location - [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined +- [ ] Quality criteria defined for each step - [ ] `deepwork sync` executed successfully -- [ ] Rules considered (suggest if genuinely helpful) - -## Output - -Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. +- [ ] Considered relevant rules for this job ### Job Context diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index b9dfa066..1f13517d 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -2,7 +2,7 @@ name: deepwork_jobs.learn description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." context: fork -agent: deepwork-jobs +agent: experts --- @@ -21,71 +21,116 @@ agent: deepwork-jobs ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. +Reflect on the conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture run-specific learnings in AGENTS.md files. ## Task -Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** - Update job instruction files -- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic +Analyze conversation history to extract learnings, then apply them: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md in the working folder -### Process +### Step 1: Analyze Conversation for Job Executions -1. **Analyze conversation for job executions** - - Scan for DeepWork slash commands (`/job_name.step_id`) - - Identify which jobs and steps were executed - - If unclear, run `git diff` to see where changes were made +1. **Scan the conversation** for DeepWork slash commands (`/job_name.step_id`) +2. **Identify the target folder** - the deepest common folder for all work on the topic +3. **If no job specified**, ask which job to learn from -2. **Identify issues and patterns** - - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs - - **Inefficiency**: extra iterations, repeated information, missing context - - **Errors**: failed validations, edge cases, quality criteria issues - - **Successes**: what worked well, efficient approaches +### Step 2: Identify Confusion and Inefficiency -3. **Classify each learning** - - **Generalizable**: would help ANY future run (update instructions) - - **Doc spec-related**: improves document quality criteria (update doc specs) - - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) +Review the conversation for: -4. **Update job instructions** (generalizable learnings) - - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep concise - avoid redundancy - - Extract shared content to `steps/shared/` if needed +**Confusion signals**: +- Unnecessary questions the agent asked +- Misunderstandings about step requirements +- Incorrect outputs needing correction +- Ambiguous instructions causing wrong interpretations -5. **Update doc specs** (if applicable) - - Edit `.deepwork/doc_specs/[doc_spec_name].md` - - Update quality criteria or document structure +**Inefficiency signals**: +- Extra iterations needed +- Repeated information +- Missing context +- Unclear dependencies -6. **Create/update AGENTS.md** (bespoke learnings) - - Place in deepest common folder for the topic - - Use file references instead of duplicating content - - Pattern: "See `path/to/file.ext` for [description]" +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -7. **Update version and sync** - - Bump version in job.yml (patch for instructions, minor for criteria) - - Add changelog entry - - Run `deepwork sync` if instructions were modified +**Success patterns**: +- What worked well +- Efficient approaches worth preserving +- Good examples to add to instructions -### File Reference Patterns +### Step 3: Classify Learnings -**Good (references)**: +For each learning, determine if it is: + +**Generalizable** (update instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions +- Adds helpful examples + +**Doc spec-related** (update doc spec files): +- Improvements to document quality criteria +- Changes to document structure or format + +**Bespoke** (add to AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions +- References specific files or paths +- Would not apply to other uses + +### Step 4: Update Job Instructions (Generalizable) + +For each generalizable learning: + +1. Locate `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements: + - Add missing context + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria +3. Keep instructions concise - avoid redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) + +### Step 5: Update Doc Specs (if applicable) + +If doc spec-related learnings identified: + +1. Locate doc spec at `.deepwork/doc_specs/[doc_spec_name].md` +2. Update quality_criteria, example document, or metadata as needed + +### Step 6: Create/Update AGENTS.md (Bespoke) + +1. Place in the deepest common folder for the topic +2. Use file references instead of duplicating content: "See `path/to/file.ext` for [description]" +3. Follow structure in `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` + +**Good patterns** (references): ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` ``` -**Avoid (duplicating)**: +**Avoid** (duplicating): ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` +### Step 7: Update Job Version and Sync + +If instructions were modified: + +1. Bump version in job.yml (patch for improvements, minor for quality criteria changes) +2. Add changelog entry +3. Run `deepwork sync` + ## Output -- Updated instruction files (generalizable improvements) +- Updated job instructions (generalizable learnings) - Updated doc specs (if applicable) -- AGENTS.md in the correct working folder (bespoke learnings) - -Include `Quality Criteria Met` when complete. +- AGENTS.md with bespoke learnings in the correct working folder ### Job Context diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 6bbaee05..43c2247a 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -3,7 +3,7 @@ name: deepwork_jobs.review_job_spec description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." user-invocable: false context: fork -agent: deepwork-jobs +agent: experts --- @@ -28,55 +28,80 @@ Before proceeding, confirm these steps are complete: ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against doc spec quality criteria, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A fresh review catches issues that might be missed after being deeply involved in definition. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. +Review the job.yml against all 9 doc spec quality criteria, fix any failures, and repeat until all pass. -### Process +### Step 1: Read the Files -1. **Read the files** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Read `.deepwork/doc_specs/job_spec.md` for reference +Read the job specification: +``` +.deepwork/jobs/[job_name]/job.yml +``` -2. **Spawn review sub-agent** - - Use Task tool with `subagent_type: general-purpose` and `model: haiku` - - Include the full job.yml content and all 9 quality criteria in the prompt - - Request PASS/FAIL for each criterion with specific issues if failed +Read the doc spec for reference: +``` +.deepwork/doc_specs/job_spec.md +``` -3. **Fix failed criteria** - - Edit job.yml to address each failed criterion - - Common fixes: shorten summary, add changelog, fix dependencies +### Step 2: Evaluate Against Quality Criteria -4. **Re-run review if needed** - - Spawn a new sub-agent with updated content - - Repeat until all 9 criteria pass +Review the job.yml against these 9 criteria: -5. **Confirm completion** - - Announce "All 9 doc spec quality criteria pass" - - Include `Quality Criteria Met` - - Guide to next step: `/deepwork_jobs.implement` +1. **Valid Identifier** - Job name is lowercase with underscores, no spaces or special characters +2. **Semantic Version** - Version follows X.Y.Z format (e.g., `1.0.0`) +3. **Concise Summary** - Summary is under 200 characters and clearly describes the job +4. **Rich Description** - Description is multi-line and explains: problem solved, process, expected outcomes, target users +5. **Changelog Present** - Includes changelog array with at least initial version entry +6. **Complete Steps** - Each step has: id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies** - Dependencies reference existing step IDs with no circular references +8. **Input Consistency** - File inputs with `from_step` reference a step in the dependencies array +9. **Output Paths** - Outputs are valid filenames or paths -### The 9 Quality Criteria +For each criterion, determine PASS or FAIL. If FAIL, note the specific issue and fix. -1. **Valid Identifier**: lowercase with underscores, no spaces -2. **Semantic Version**: X.Y.Z format -3. **Concise Summary**: under 200 characters -4. **Rich Description**: multi-line with problem/process/outcome/users -5. **Changelog Present**: array with at least initial version -6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: reference existing steps, no circular refs -8. **Input Consistency**: from_step must be in dependencies -9. **Output Paths**: valid filenames or paths +### Step 3: Fix Failed Criteria + +For each failed criterion, edit the job.yml: + +| Criterion | Common Issue | Fix | +|-----------|-------------|-----| +| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | +| Semantic Version | Invalid format | Set to `"1.0.0"` | +| Concise Summary | Too long | Shorten to <200 chars | +| Rich Description | Single line | Add multi-line explanation | +| Changelog Present | Missing | Add changelog with initial version | +| Complete Steps | Missing fields | Add required fields | +| Valid Dependencies | Non-existent step | Fix step ID reference | +| Input Consistency | from_step not in deps | Add step to dependencies | +| Output Paths | Invalid format | Use valid filename/path | + +### Step 4: Re-Evaluate (If Needed) + +If any criteria failed: +1. Review the updated job.yml +2. Re-evaluate all criteria +3. Fix remaining issues +4. Repeat until all 9 pass + +### Step 5: Confirm Completion + +When all 9 criteria pass: + +1. Announce: "All 9 doc spec quality criteria pass." +2. List what was validated +3. Include: `Quality Criteria Met` +4. Guide to next step: "Run `/deepwork_jobs.implement` to generate the step instruction files." ## Output -The validated `job.yml` file that passes all quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 quality criteria. ### Job Context diff --git a/.deepwork/jobs/deepwork_jobs/AGENTS.md b/.deepwork/jobs/deepwork_jobs/AGENTS.md index be54401a..6d97d0e5 100644 --- a/.deepwork/jobs/deepwork_jobs/AGENTS.md +++ b/.deepwork/jobs/deepwork_jobs/AGENTS.md @@ -54,37 +54,7 @@ deepwork_jobs/ - Bump minor version (0.x.0) for new features or structural changes - Always update changelog when bumping version -## Learnings - -### AskUserQuestion Tool Does Not Exist (2026-02-01) - -**Issue**: The step instructions and expert documentation referenced a tool called -`AskUserQuestion` that does not exist in Claude Code's toolset. - -**Symptom**: When running the define step, the agent would output all questions as -a plain text list instead of asking them interactively one at a time. - -**Root Cause**: The phrase "ask structured questions" was documented as triggering -the `AskUserQuestion` tool, but this was aspirational - the tool was never -implemented in Claude Code. - -**Fix Applied**: -- Removed all references to `AskUserQuestion` tool -- Updated instructions to say "ask questions one at a time" -- Clarified that questions should be presented individually with waits for responses - -**Files Changed**: -- `src/deepwork/standard_jobs/deepwork_jobs/steps/define.md` -- `src/deepwork/standard_jobs/deepwork_rules/steps/define.md` -- `src/deepwork/standard/experts/deepwork_jobs/topics/step_instructions.md` -- `library/jobs/spec_driven_development/steps/*.md` (multiple files) - -**Lesson**: Do not reference tools in instructions unless they actually exist. -When specifying interactive behavior, be explicit about the expected pattern -(one question at a time, wait for response) rather than referencing hypothetical -tooling. - ## Last Updated -- Date: 2026-02-01 -- From conversation about: Learning why define step output questions as plain text +- Date: 2026-01-15 +- From conversation about: Adding make_new_job.sh script and templates directory diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 6b806bc9..f3c7f6b7 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "1.0.0" +version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -22,6 +22,8 @@ workflows: - implement changelog: + - version: "1.1.0" + changes: "Added expert delegation to all steps via agent: experts; cleaned up and simplified step instructions; removed inline quality_criteria from job.yml (handled by doc specs and step instructions)" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - version: "0.1.0" @@ -48,7 +50,7 @@ steps: name: "Define Job Specification" description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." instructions_file: steps/define.md - agent: deepwork-jobs + agent: experts inputs: - name: job_purpose description: "What complex task or workflow are you trying to accomplish?" @@ -61,7 +63,7 @@ steps: name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." instructions_file: steps/review_job_spec.md - agent: deepwork-jobs + agent: experts inputs: - file: job.yml from_step: define @@ -75,7 +77,7 @@ steps: name: "Implement Job Steps" description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." instructions_file: steps/implement.md - agent: deepwork-jobs + agent: experts inputs: - file: job.yml from_step: review_job_spec @@ -88,7 +90,7 @@ steps: name: "Learn from Job Execution" description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." instructions_file: steps/learn.md - agent: deepwork-jobs + agent: experts exposed: true inputs: - name: job_name diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index 0e366fd8..5719e1f3 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -2,51 +2,102 @@ ## Objective -Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. +Create a `job.yml` specification file that defines a new DeepWork job by understanding the user's workflow requirements through interactive questioning. ## Task Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -### Process +### Phase 1: Understand the Job Purpose -1. **Understand the job purpose** - - Ask structured questions about the overall goal, domain, and frequency - - Understand what success looks like and who the audience is - - Identify the major phases of the workflow +Ask structured questions to understand the workflow: -2. **Detect document-oriented workflows** - - Look for patterns: "report", "summary", "monthly", "for stakeholders" - - If detected, offer to create a doc spec for consistent quality - - Use `.deepwork/doc_specs/job_spec.md` as a reference example +1. **Overall goal** - What complex task are they trying to accomplish? What domain (research, marketing, development, reporting)? -3. **Define each step** - - For each phase, gather: purpose, inputs, outputs, dependencies - - Ask about output file paths and organization - - Consider whether steps need agent delegation +2. **Success criteria** - What's the final deliverable? Who is the audience? What quality matters most? -4. **Validate the workflow** - - Summarize the complete workflow - - Check for gaps in inputs/outputs between steps - - Confirm job name, summary, and version +3. **Major phases** - What are the distinct stages from start to finish? Any dependencies between phases? -5. **Create the job specification** - - Run `make_new_job.sh` to create directory structure: - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` - - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` +### Phase 2: Detect Document-Oriented Workflows -### Key Guidelines +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly", "for stakeholders" +- Final deliverable is a specific document type +- Recurring documents with consistent structure -- **Use `AskUserQuestion` tool for all questions** - Never output questions as plain text. Always use the AskUserQuestion tool to gather user input with structured options. Ask questions one at a time, wait for the response, then ask the next. -- **Work products go in main repo**, not `.deepwork/` (for discoverability) -- **Use dates in paths** for periodic outputs that accumulate -- **Use `_dataroom` folders** for supporting materials -- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` +**If detected**, offer to create a doc spec: +1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first." +2. Ask if they want to create a doc spec, use existing one, or skip + +**If creating a doc spec**, gather: +- Document name and purpose +- Target audience and frequency +- Quality criteria (3-5, focused on the output document itself) +- Document structure (sections, required elements) + +Create at `.deepwork/doc_specs/[doc_spec_name].md`. Reference `.deepwork/doc_specs/job_spec.md` for an example. + +### Phase 3: Define Each Step + +For each major phase, gather: + +1. **Purpose** - What does this step accomplish? What are inputs and outputs? + +2. **Inputs**: + - User-provided parameters (e.g., topic, target audience)? + - Files from previous steps? + +3. **Outputs**: + - What files does this step produce? + - Format (markdown, YAML, JSON)? + - Where to save? (Use meaningful paths like `competitive_research/analysis.md`, not `.deepwork/outputs/`) + - Does this output have a doc spec? + +4. **Dependencies** - Which previous steps must complete first? + +5. **Process** - Key activities? Quality checks needed? + +6. **Agent Delegation** - Should this step run via a specific agent? Use `agent: experts` for domain-specific expertise. + +#### Output Path Guidelines + +- Place outputs in main repo, not dot-directories +- Use job name as top-level folder for job-specific outputs +- Include dates for periodic outputs that accumulate (monthly reports) +- Omit dates for current-state outputs that get updated in place +- Use `_dataroom` folders for supporting materials + +### Phase 4: Validate the Workflow + +After gathering all step information: + +1. **Review the flow** - Summarize the complete workflow, show how outputs feed into next steps +2. **Check for gaps** - Undefined inputs? Unused outputs? Circular dependencies? +3. **Confirm details** - Job name (lowercase_underscores), summary (max 200 chars), description (detailed), version (1.0.0) + +### Phase 5: Create the Job + +Create the directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml`. + +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for structure and `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a complete example. + +**Validation rules**: +- Job name: lowercase, underscores, no spaces +- Version: semantic versioning (1.0.0) +- Summary: under 200 characters +- Step IDs: unique, lowercase with underscores +- Dependencies must reference existing steps +- File inputs with `from_step` must be in dependencies +- At least one output per step ## Output -Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. +**File**: `.deepwork/jobs/[job_name]/job.yml` After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md index 214338ea..6dbad31b 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md @@ -2,62 +2,102 @@ ## Objective -Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the job.yml and create comprehensive instruction files for each step. +Read the `job.yml` specification and create all necessary files to make the job functional, then sync the commands. -### Process +### Step 1: Create Directory Structure -1. **Create directory structure** (if needed) - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` +Run the `make_new_job.sh` script: -2. **Read and validate the specification** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Extract job name, description, and step details - - Understand the workflow structure +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` -3. **Generate step instruction files** - - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step - - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference - - Each file must include: Objective, Task, Process, Output Format, Quality Criteria +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -4. **Sync skills** - ```bash - deepwork sync - ``` +**Note**: If directory exists from define step, skip or just create missing subdirectories. -5. **Consider rules for the new job** - - Think about whether rules would help maintain quality - - If relevant, explain and offer to run `/deepwork_rules.define` +### Step 2: Read and Validate the Specification -### Instruction File Guidelines +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate: name, version, summary, description, steps are present +3. Check dependencies reference existing steps, no circular dependencies +4. Verify file inputs match dependencies -- **Be specific** - tailor to each step's purpose, not generic advice -- **Provide examples** - show what good output looks like -- **Include quality criteria** - how to verify the step is complete -- **Use "ask structured questions"** - for steps that gather user input -- **Align with hooks** - if step has hooks, match the validation criteria +### Step 3: Generate Step Instruction Files -### Templates Available +For each step in job.yml, create `.deepwork/jobs/[job_name]/steps/[step_id].md`. -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- Examples: `job.yml.example`, `step_instruction.md.example` +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for structure. + +**Guidelines**: + +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to the step's purpose, not generic +3. **Provide examples** - Show what good output looks like +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - Steps with user inputs MUST explicitly tell the agent to "ask structured questions" +6. **Align with hooks** - If step has `stop_hooks`, ensure quality criteria match the hooks + +Each instruction file should include: +- **Objective** - What this step accomplishes +- **Task** - Detailed process +- **Output Format** - Examples of expected outputs +- **Quality Criteria** - How to verify completion + +### Step 4: Verify job.yml Location + +Ensure `job.yml` is at `.deepwork/jobs/[job_name]/job.yml`. + +### Step 5: Sync Skills + +Run: + +```bash +deepwork sync +``` + +This generates skills in `.claude/skills/` (or appropriate platform directory). + +### Step 6: Consider Rules + +After implementing, consider whether **rules** would help this job's domain. + +**What are rules?** Automated guardrails that trigger when certain files change, ensuring: +- Documentation stays in sync +- Team guidelines are followed +- Quality standards are maintained + +**When to suggest rules:** +- Does this job produce outputs that other files depend on? +- Are there docs that should update when outputs change? +- Could changes impact other parts of the project? + +**Examples**: +| Job Type | Potential Rule | +|----------|----------------| +| API Design | "Update API docs when endpoint definitions change" | +| Competitive Research | "Update strategy docs when competitor analysis changes" | +| Feature Development | "Update changelog when feature files change" | + +If you identify helpful rules, explain what they would do and offer: "Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up." + +**Note**: Not every job needs rules. Only suggest when genuinely helpful. ## Completion Checklist +- [ ] job.yml in correct location - [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined +- [ ] Quality criteria defined for each step - [ ] `deepwork sync` executed successfully -- [ ] Rules considered (suggest if genuinely helpful) - -## Output - -Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. +- [ ] Considered relevant rules for this job diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md index f7175cb4..9b14ef06 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -2,68 +2,113 @@ ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. +Reflect on the conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture run-specific learnings in AGENTS.md files. ## Task -Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** - Update job instruction files -- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic +Analyze conversation history to extract learnings, then apply them: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md in the working folder -### Process +### Step 1: Analyze Conversation for Job Executions -1. **Analyze conversation for job executions** - - Scan for DeepWork slash commands (`/job_name.step_id`) - - Identify which jobs and steps were executed - - If unclear, run `git diff` to see where changes were made +1. **Scan the conversation** for DeepWork slash commands (`/job_name.step_id`) +2. **Identify the target folder** - the deepest common folder for all work on the topic +3. **If no job specified**, ask which job to learn from -2. **Identify issues and patterns** - - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs - - **Inefficiency**: extra iterations, repeated information, missing context - - **Errors**: failed validations, edge cases, quality criteria issues - - **Successes**: what worked well, efficient approaches +### Step 2: Identify Confusion and Inefficiency -3. **Classify each learning** - - **Generalizable**: would help ANY future run (update instructions) - - **Doc spec-related**: improves document quality criteria (update doc specs) - - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) +Review the conversation for: -4. **Update job instructions** (generalizable learnings) - - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep concise - avoid redundancy - - Extract shared content to `steps/shared/` if needed +**Confusion signals**: +- Unnecessary questions the agent asked +- Misunderstandings about step requirements +- Incorrect outputs needing correction +- Ambiguous instructions causing wrong interpretations -5. **Update doc specs** (if applicable) - - Edit `.deepwork/doc_specs/[doc_spec_name].md` - - Update quality criteria or document structure +**Inefficiency signals**: +- Extra iterations needed +- Repeated information +- Missing context +- Unclear dependencies -6. **Create/update AGENTS.md** (bespoke learnings) - - Place in deepest common folder for the topic - - Use file references instead of duplicating content - - Pattern: "See `path/to/file.ext` for [description]" +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -7. **Update version and sync** - - Bump version in job.yml (patch for instructions, minor for criteria) - - Add changelog entry - - Run `deepwork sync` if instructions were modified +**Success patterns**: +- What worked well +- Efficient approaches worth preserving +- Good examples to add to instructions -### File Reference Patterns +### Step 3: Classify Learnings -**Good (references)**: +For each learning, determine if it is: + +**Generalizable** (update instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions +- Adds helpful examples + +**Doc spec-related** (update doc spec files): +- Improvements to document quality criteria +- Changes to document structure or format + +**Bespoke** (add to AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions +- References specific files or paths +- Would not apply to other uses + +### Step 4: Update Job Instructions (Generalizable) + +For each generalizable learning: + +1. Locate `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements: + - Add missing context + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria +3. Keep instructions concise - avoid redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) + +### Step 5: Update Doc Specs (if applicable) + +If doc spec-related learnings identified: + +1. Locate doc spec at `.deepwork/doc_specs/[doc_spec_name].md` +2. Update quality_criteria, example document, or metadata as needed + +### Step 6: Create/Update AGENTS.md (Bespoke) + +1. Place in the deepest common folder for the topic +2. Use file references instead of duplicating content: "See `path/to/file.ext` for [description]" +3. Follow structure in `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` + +**Good patterns** (references): ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` ``` -**Avoid (duplicating)**: +**Avoid** (duplicating): ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` +### Step 7: Update Job Version and Sync + +If instructions were modified: + +1. Bump version in job.yml (patch for improvements, minor for quality criteria changes) +2. Add changelog entry +3. Run `deepwork sync` + ## Output -- Updated instruction files (generalizable improvements) +- Updated job instructions (generalizable learnings) - Updated doc specs (if applicable) -- AGENTS.md in the correct working folder (bespoke learnings) - -Include `Quality Criteria Met` when complete. +- AGENTS.md with bespoke learnings in the correct working folder diff --git a/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md b/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md index 621cfa6b..7261fe9d 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md +++ b/.deepwork/jobs/deepwork_jobs/steps/review_job_spec.md @@ -2,52 +2,77 @@ ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against doc spec quality criteria, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A fresh review catches issues that might be missed after being deeply involved in definition. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. +Review the job.yml against all 9 doc spec quality criteria, fix any failures, and repeat until all pass. -### Process +### Step 1: Read the Files -1. **Read the files** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Read `.deepwork/doc_specs/job_spec.md` for reference +Read the job specification: +``` +.deepwork/jobs/[job_name]/job.yml +``` -2. **Spawn review sub-agent** - - Use Task tool with `subagent_type: general-purpose` and `model: haiku` - - Include the full job.yml content and all 9 quality criteria in the prompt - - Request PASS/FAIL for each criterion with specific issues if failed +Read the doc spec for reference: +``` +.deepwork/doc_specs/job_spec.md +``` -3. **Fix failed criteria** - - Edit job.yml to address each failed criterion - - Common fixes: shorten summary, add changelog, fix dependencies +### Step 2: Evaluate Against Quality Criteria -4. **Re-run review if needed** - - Spawn a new sub-agent with updated content - - Repeat until all 9 criteria pass +Review the job.yml against these 9 criteria: -5. **Confirm completion** - - Announce "All 9 doc spec quality criteria pass" - - Include `Quality Criteria Met` - - Guide to next step: `/deepwork_jobs.implement` +1. **Valid Identifier** - Job name is lowercase with underscores, no spaces or special characters +2. **Semantic Version** - Version follows X.Y.Z format (e.g., `1.0.0`) +3. **Concise Summary** - Summary is under 200 characters and clearly describes the job +4. **Rich Description** - Description is multi-line and explains: problem solved, process, expected outcomes, target users +5. **Changelog Present** - Includes changelog array with at least initial version entry +6. **Complete Steps** - Each step has: id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies** - Dependencies reference existing step IDs with no circular references +8. **Input Consistency** - File inputs with `from_step` reference a step in the dependencies array +9. **Output Paths** - Outputs are valid filenames or paths -### The 9 Quality Criteria +For each criterion, determine PASS or FAIL. If FAIL, note the specific issue and fix. -1. **Valid Identifier**: lowercase with underscores, no spaces -2. **Semantic Version**: X.Y.Z format -3. **Concise Summary**: under 200 characters -4. **Rich Description**: multi-line with problem/process/outcome/users -5. **Changelog Present**: array with at least initial version -6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: reference existing steps, no circular refs -8. **Input Consistency**: from_step must be in dependencies -9. **Output Paths**: valid filenames or paths +### Step 3: Fix Failed Criteria + +For each failed criterion, edit the job.yml: + +| Criterion | Common Issue | Fix | +|-----------|-------------|-----| +| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | +| Semantic Version | Invalid format | Set to `"1.0.0"` | +| Concise Summary | Too long | Shorten to <200 chars | +| Rich Description | Single line | Add multi-line explanation | +| Changelog Present | Missing | Add changelog with initial version | +| Complete Steps | Missing fields | Add required fields | +| Valid Dependencies | Non-existent step | Fix step ID reference | +| Input Consistency | from_step not in deps | Add step to dependencies | +| Output Paths | Invalid format | Use valid filename/path | + +### Step 4: Re-Evaluate (If Needed) + +If any criteria failed: +1. Review the updated job.yml +2. Re-evaluate all criteria +3. Fix remaining issues +4. Repeat until all 9 pass + +### Step 5: Confirm Completion + +When all 9 criteria pass: + +1. Announce: "All 9 doc spec quality criteria pass." +2. List what was validated +3. Include: `Quality Criteria Met` +4. Guide to next step: "Run `/deepwork_jobs.implement` to generate the step instruction files." ## Output -The validated `job.yml` file that passes all quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 quality criteria. diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 82265477..4327a093 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -22,52 +22,103 @@ prompt = """ ## Objective -Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions. +Create a `job.yml` specification file that defines a new DeepWork job by understanding the user's workflow requirements through interactive questioning. ## Task Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -### Process +### Phase 1: Understand the Job Purpose -1. **Understand the job purpose** - - Ask structured questions about the overall goal, domain, and frequency - - Understand what success looks like and who the audience is - - Identify the major phases of the workflow +Ask structured questions to understand the workflow: -2. **Detect document-oriented workflows** - - Look for patterns: "report", "summary", "monthly", "for stakeholders" - - If detected, offer to create a doc spec for consistent quality - - Use `.deepwork/doc_specs/job_spec.md` as a reference example +1. **Overall goal** - What complex task are they trying to accomplish? What domain (research, marketing, development, reporting)? -3. **Define each step** - - For each phase, gather: purpose, inputs, outputs, dependencies - - Ask about output file paths and organization - - Consider whether steps need agent delegation +2. **Success criteria** - What's the final deliverable? Who is the audience? What quality matters most? -4. **Validate the workflow** - - Summarize the complete workflow - - Check for gaps in inputs/outputs between steps - - Confirm job name, summary, and version +3. **Major phases** - What are the distinct stages from start to finish? Any dependencies between phases? -5. **Create the job specification** - - Run `make_new_job.sh` to create directory structure: - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` - - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml` +### Phase 2: Detect Document-Oriented Workflows -### Key Guidelines +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly", "for stakeholders" +- Final deliverable is a specific document type +- Recurring documents with consistent structure -- **Use `AskUserQuestion` tool for all questions** - Never output questions as plain text. Always use the AskUserQuestion tool to gather user input with structured options. Ask questions one at a time, wait for the response, then ask the next. -- **Work products go in main repo**, not `.deepwork/` (for discoverability) -- **Use dates in paths** for periodic outputs that accumulate -- **Use `_dataroom` folders** for supporting materials -- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/` +**If detected**, offer to create a doc spec: +1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first." +2. Ask if they want to create a doc spec, use existing one, or skip + +**If creating a doc spec**, gather: +- Document name and purpose +- Target audience and frequency +- Quality criteria (3-5, focused on the output document itself) +- Document structure (sections, required elements) + +Create at `.deepwork/doc_specs/[doc_spec_name].md`. Reference `.deepwork/doc_specs/job_spec.md` for an example. + +### Phase 3: Define Each Step + +For each major phase, gather: + +1. **Purpose** - What does this step accomplish? What are inputs and outputs? + +2. **Inputs**: + - User-provided parameters (e.g., topic, target audience)? + - Files from previous steps? + +3. **Outputs**: + - What files does this step produce? + - Format (markdown, YAML, JSON)? + - Where to save? (Use meaningful paths like `competitive_research/analysis.md`, not `.deepwork/outputs/`) + - Does this output have a doc spec? + +4. **Dependencies** - Which previous steps must complete first? + +5. **Process** - Key activities? Quality checks needed? + +6. **Agent Delegation** - Should this step run via a specific agent? Use `agent: experts` for domain-specific expertise. + +#### Output Path Guidelines + +- Place outputs in main repo, not dot-directories +- Use job name as top-level folder for job-specific outputs +- Include dates for periodic outputs that accumulate (monthly reports) +- Omit dates for current-state outputs that get updated in place +- Use `_dataroom` folders for supporting materials + +### Phase 4: Validate the Workflow + +After gathering all step information: + +1. **Review the flow** - Summarize the complete workflow, show how outputs feed into next steps +2. **Check for gaps** - Undefined inputs? Unused outputs? Circular dependencies? +3. **Confirm details** - Job name (lowercase_underscores), summary (max 200 chars), description (detailed), version (1.0.0) + +### Phase 5: Create the Job + +Create the directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml`. + +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for structure and `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a complete example. + +**Validation rules**: +- Job name: lowercase, underscores, no spaces +- Version: semantic versioning (1.0.0) +- Summary: under 200 characters +- Step IDs: unique, lowercase with underscores +- Dependencies must reference existing steps +- File inputs with `from_step` must be in dependencies +- At least one output per step ## Output -Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`. +**File**: `.deepwork/jobs/[job_name]/job.yml` After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml index b005e5a4..e6c02a1f 100644 --- a/.gemini/skills/deepwork_jobs/implement.toml +++ b/.gemini/skills/deepwork_jobs/implement.toml @@ -26,65 +26,105 @@ Before proceeding, confirm these steps are complete: ## Objective -Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the job.yml and create comprehensive instruction files for each step. +Read the `job.yml` specification and create all necessary files to make the job functional, then sync the commands. -### Process +### Step 1: Create Directory Structure -1. **Create directory structure** (if needed) - ```bash - .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] - ``` +Run the `make_new_job.sh` script: -2. **Read and validate the specification** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Extract job name, description, and step details - - Understand the workflow structure +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` -3. **Generate step instruction files** - - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step - - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference - - Each file must include: Objective, Task, Process, Output Format, Quality Criteria +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -4. **Sync skills** - ```bash - deepwork sync - ``` +**Note**: If directory exists from define step, skip or just create missing subdirectories. -5. **Consider rules for the new job** - - Think about whether rules would help maintain quality - - If relevant, explain and offer to run `/deepwork_rules.define` +### Step 2: Read and Validate the Specification -### Instruction File Guidelines +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate: name, version, summary, description, steps are present +3. Check dependencies reference existing steps, no circular dependencies +4. Verify file inputs match dependencies -- **Be specific** - tailor to each step's purpose, not generic advice -- **Provide examples** - show what good output looks like -- **Include quality criteria** - how to verify the step is complete -- **Use "ask structured questions"** - for steps that gather user input -- **Align with hooks** - if step has hooks, match the validation criteria +### Step 3: Generate Step Instruction Files -### Templates Available +For each step in job.yml, create `.deepwork/jobs/[job_name]/steps/[step_id].md`. -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- Examples: `job.yml.example`, `step_instruction.md.example` +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for structure. + +**Guidelines**: + +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to the step's purpose, not generic +3. **Provide examples** - Show what good output looks like +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - Steps with user inputs MUST explicitly tell the agent to "ask structured questions" +6. **Align with hooks** - If step has `stop_hooks`, ensure quality criteria match the hooks + +Each instruction file should include: +- **Objective** - What this step accomplishes +- **Task** - Detailed process +- **Output Format** - Examples of expected outputs +- **Quality Criteria** - How to verify completion + +### Step 4: Verify job.yml Location + +Ensure `job.yml` is at `.deepwork/jobs/[job_name]/job.yml`. + +### Step 5: Sync Skills + +Run: + +```bash +deepwork sync +``` + +This generates skills in `.claude/skills/` (or appropriate platform directory). + +### Step 6: Consider Rules + +After implementing, consider whether **rules** would help this job's domain. + +**What are rules?** Automated guardrails that trigger when certain files change, ensuring: +- Documentation stays in sync +- Team guidelines are followed +- Quality standards are maintained + +**When to suggest rules:** +- Does this job produce outputs that other files depend on? +- Are there docs that should update when outputs change? +- Could changes impact other parts of the project? + +**Examples**: +| Job Type | Potential Rule | +|----------|----------------| +| API Design | "Update API docs when endpoint definitions change" | +| Competitive Research | "Update strategy docs when competitor analysis changes" | +| Feature Development | "Update changelog when feature files change" | + +If you identify helpful rules, explain what they would do and offer: "Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up." + +**Note**: Not every job needs rules. Only suggest when genuinely helpful. ## Completion Checklist +- [ ] job.yml in correct location - [ ] All step instruction files created (not stubs) - [ ] Instructions are specific and actionable - [ ] Output examples provided -- [ ] Quality criteria defined +- [ ] Quality criteria defined for each step - [ ] `deepwork sync` executed successfully -- [ ] Rules considered (suggest if genuinely helpful) - -## Output - -Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`. +- [ ] Considered relevant rules for this job ### Job Context diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index 76311171..6d53d8f7 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -22,71 +22,116 @@ prompt = """ ## Objective -Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files. +Reflect on the conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture run-specific learnings in AGENTS.md files. ## Task -Analyze the conversation history to extract learnings and apply them appropriately: -- **Generalizable learnings** - Update job instruction files -- **Bespoke learnings** - Add to AGENTS.md in the deepest common folder for the topic +Analyze conversation history to extract learnings, then apply them: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md in the working folder -### Process +### Step 1: Analyze Conversation for Job Executions -1. **Analyze conversation for job executions** - - Scan for DeepWork slash commands (`/job_name.step_id`) - - Identify which jobs and steps were executed - - If unclear, run `git diff` to see where changes were made +1. **Scan the conversation** for DeepWork slash commands (`/job_name.step_id`) +2. **Identify the target folder** - the deepest common folder for all work on the topic +3. **If no job specified**, ask which job to learn from -2. **Identify issues and patterns** - - **Confusion**: unnecessary questions, misunderstandings, incorrect outputs - - **Inefficiency**: extra iterations, repeated information, missing context - - **Errors**: failed validations, edge cases, quality criteria issues - - **Successes**: what worked well, efficient approaches +### Step 2: Identify Confusion and Inefficiency -3. **Classify each learning** - - **Generalizable**: would help ANY future run (update instructions) - - **Doc spec-related**: improves document quality criteria (update doc specs) - - **Bespoke**: specific to THIS project/codebase (add to AGENTS.md) +Review the conversation for: -4. **Update job instructions** (generalizable learnings) - - Edit `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep concise - avoid redundancy - - Extract shared content to `steps/shared/` if needed +**Confusion signals**: +- Unnecessary questions the agent asked +- Misunderstandings about step requirements +- Incorrect outputs needing correction +- Ambiguous instructions causing wrong interpretations -5. **Update doc specs** (if applicable) - - Edit `.deepwork/doc_specs/[doc_spec_name].md` - - Update quality criteria or document structure +**Inefficiency signals**: +- Extra iterations needed +- Repeated information +- Missing context +- Unclear dependencies -6. **Create/update AGENTS.md** (bespoke learnings) - - Place in deepest common folder for the topic - - Use file references instead of duplicating content - - Pattern: "See `path/to/file.ext` for [description]" +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -7. **Update version and sync** - - Bump version in job.yml (patch for instructions, minor for criteria) - - Add changelog entry - - Run `deepwork sync` if instructions were modified +**Success patterns**: +- What worked well +- Efficient approaches worth preserving +- Good examples to add to instructions -### File Reference Patterns +### Step 3: Classify Learnings -**Good (references)**: +For each learning, determine if it is: + +**Generalizable** (update instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions +- Adds helpful examples + +**Doc spec-related** (update doc spec files): +- Improvements to document quality criteria +- Changes to document structure or format + +**Bespoke** (add to AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions +- References specific files or paths +- Would not apply to other uses + +### Step 4: Update Job Instructions (Generalizable) + +For each generalizable learning: + +1. Locate `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements: + - Add missing context + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria +3. Keep instructions concise - avoid redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) + +### Step 5: Update Doc Specs (if applicable) + +If doc spec-related learnings identified: + +1. Locate doc spec at `.deepwork/doc_specs/[doc_spec_name].md` +2. Update quality_criteria, example document, or metadata as needed + +### Step 6: Create/Update AGENTS.md (Bespoke) + +1. Place in the deepest common folder for the topic +2. Use file references instead of duplicating content: "See `path/to/file.ext` for [description]" +3. Follow structure in `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` + +**Good patterns** (references): ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` ``` -**Avoid (duplicating)**: +**Avoid** (duplicating): ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } ``` +### Step 7: Update Job Version and Sync + +If instructions were modified: + +1. Bump version in job.yml (patch for improvements, minor for quality criteria changes) +2. Add changelog entry +3. Run `deepwork sync` + ## Output -- Updated instruction files (generalizable improvements) +- Updated job instructions (generalizable learnings) - Updated doc specs (if applicable) -- AGENTS.md in the correct working folder (bespoke learnings) - -Include `Quality Criteria Met` when complete. +- AGENTS.md with bespoke learnings in the correct working folder ### Job Context diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index 9d917093..db693323 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -26,55 +26,80 @@ Before proceeding, confirm these steps are complete: ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against doc spec quality criteria, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A sub-agent provides "fresh eyes" that catch issues the main agent might miss. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A fresh review catches issues that might be missed after being deeply involved in definition. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. +Review the job.yml against all 9 doc spec quality criteria, fix any failures, and repeat until all pass. -### Process +### Step 1: Read the Files -1. **Read the files** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Read `.deepwork/doc_specs/job_spec.md` for reference +Read the job specification: +``` +.deepwork/jobs/[job_name]/job.yml +``` -2. **Spawn review sub-agent** - - Use Task tool with `subagent_type: general-purpose` and `model: haiku` - - Include the full job.yml content and all 9 quality criteria in the prompt - - Request PASS/FAIL for each criterion with specific issues if failed +Read the doc spec for reference: +``` +.deepwork/doc_specs/job_spec.md +``` -3. **Fix failed criteria** - - Edit job.yml to address each failed criterion - - Common fixes: shorten summary, add changelog, fix dependencies +### Step 2: Evaluate Against Quality Criteria -4. **Re-run review if needed** - - Spawn a new sub-agent with updated content - - Repeat until all 9 criteria pass +Review the job.yml against these 9 criteria: -5. **Confirm completion** - - Announce "All 9 doc spec quality criteria pass" - - Include `Quality Criteria Met` - - Guide to next step: `/deepwork_jobs.implement` +1. **Valid Identifier** - Job name is lowercase with underscores, no spaces or special characters +2. **Semantic Version** - Version follows X.Y.Z format (e.g., `1.0.0`) +3. **Concise Summary** - Summary is under 200 characters and clearly describes the job +4. **Rich Description** - Description is multi-line and explains: problem solved, process, expected outcomes, target users +5. **Changelog Present** - Includes changelog array with at least initial version entry +6. **Complete Steps** - Each step has: id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies** - Dependencies reference existing step IDs with no circular references +8. **Input Consistency** - File inputs with `from_step` reference a step in the dependencies array +9. **Output Paths** - Outputs are valid filenames or paths -### The 9 Quality Criteria +For each criterion, determine PASS or FAIL. If FAIL, note the specific issue and fix. -1. **Valid Identifier**: lowercase with underscores, no spaces -2. **Semantic Version**: X.Y.Z format -3. **Concise Summary**: under 200 characters -4. **Rich Description**: multi-line with problem/process/outcome/users -5. **Changelog Present**: array with at least initial version -6. **Complete Steps**: each has id, name, description, instructions_file, outputs, dependencies -7. **Valid Dependencies**: reference existing steps, no circular refs -8. **Input Consistency**: from_step must be in dependencies -9. **Output Paths**: valid filenames or paths +### Step 3: Fix Failed Criteria + +For each failed criterion, edit the job.yml: + +| Criterion | Common Issue | Fix | +|-----------|-------------|-----| +| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | +| Semantic Version | Invalid format | Set to `"1.0.0"` | +| Concise Summary | Too long | Shorten to <200 chars | +| Rich Description | Single line | Add multi-line explanation | +| Changelog Present | Missing | Add changelog with initial version | +| Complete Steps | Missing fields | Add required fields | +| Valid Dependencies | Non-existent step | Fix step ID reference | +| Input Consistency | from_step not in deps | Add step to dependencies | +| Output Paths | Invalid format | Use valid filename/path | + +### Step 4: Re-Evaluate (If Needed) + +If any criteria failed: +1. Review the updated job.yml +2. Re-evaluate all criteria +3. Fix remaining issues +4. Repeat until all 9 pass + +### Step 5: Confirm Completion + +When all 9 criteria pass: + +1. Announce: "All 9 doc spec quality criteria pass." +2. List what was validated +3. Include: `Quality Criteria Met` +4. Guide to next step: "Run `/deepwork_jobs.implement` to generate the step instruction files." ## Output -The validated `job.yml` file that passes all quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 quality criteria. ### Job Context diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 4343cbda..f3c7f6b7 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "1.0.0" +version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -22,6 +22,8 @@ workflows: - implement changelog: + - version: "1.1.0" + changes: "Added expert delegation to all steps via agent: experts; cleaned up and simplified step instructions; removed inline quality_criteria from job.yml (handled by doc specs and step instructions)" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - version: "0.1.0" @@ -48,6 +50,7 @@ steps: name: "Define Job Specification" description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." instructions_file: steps/define.md + agent: experts inputs: - name: job_purpose description: "What complex task or workflow are you trying to accomplish?" @@ -55,10 +58,12 @@ steps: - file: job.yml doc_spec: .deepwork/doc_specs/job_spec.md dependencies: [] + - id: review_job_spec name: "Review Job Specification" description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification." instructions_file: steps/review_job_spec.md + agent: experts inputs: - file: job.yml from_step: define @@ -67,16 +72,12 @@ steps: doc_spec: .deepwork/doc_specs/job_spec.md dependencies: - define - quality_criteria: - - "**Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review?" - - "**All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria?" - - "**Findings Addressed**: Were all failed criteria addressed by the main agent?" - - "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?" - id: implement name: "Implement Job Steps" description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes." instructions_file: steps/implement.md + agent: experts inputs: - file: job.yml from_step: review_job_spec @@ -84,21 +85,12 @@ steps: - steps/ dependencies: - review_job_spec - quality_criteria: - - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?" - - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?" - - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?" - - "**Output Examples**: Does each instruction file show what good output looks like?" - - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?" - - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?" - - "**Sync Complete**: Has `deepwork sync` been run successfully?" - - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?" - - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful." - id: learn name: "Learn from Job Execution" description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it." instructions_file: steps/learn.md + agent: experts exposed: true inputs: - name: job_name @@ -106,16 +98,3 @@ steps: outputs: - AGENTS.md dependencies: [] - quality_criteria: - - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?" - - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?" - - "**Instructions Improved**: Were job instructions updated to address identified issues?" - - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?" - - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?" - - "**doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?" - - "**doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?" - - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?" - - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?" - - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?" - - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?" - - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 31de7440..5719e1f3 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -2,457 +2,102 @@ ## 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. +Create a `job.yml` specification file that defines a new DeepWork job by understanding the user's workflow requirements through interactive questioning. ## Task -Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step. -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. +### Phase 1: Understand the Job Purpose -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`). +Ask structured questions to understand the workflow: -### Step 1: Understand the Job Purpose +1. **Overall goal** - What complex task are they trying to accomplish? What domain (research, marketing, development, reporting)? -Start by asking structured questions to understand what the user wants to accomplish: +2. **Success criteria** - What's the final deliverable? Who is the audience? What quality matters most? -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? +3. **Major phases** - What are the distinct stages from start to finish? Any dependencies between phases? -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? +### Phase 2: Detect Document-Oriented Workflows -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 1.5: Detect Document-Oriented Workflows - -**Check for document-focused patterns** in the user's description: -- Keywords: "report", "summary", "document", "create", "monthly", "quarterly", "for stakeholders", "for leadership" -- Final deliverable is a specific document (e.g., "AWS spending report", "competitive analysis", "sprint summary") +Check for document-focused patterns in the user's description: +- Keywords: "report", "summary", "document", "monthly", "quarterly", "for stakeholders" +- Final deliverable is a specific document type - Recurring documents with consistent structure -**If a document-oriented workflow is detected:** - -1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first to ensure consistent quality." - -2. Ask structured questions to understand if they want to: - - Create a doc spec for this document - - Use an existing doc spec (if any exist in `.deepwork/doc_specs/`) - - Skip doc spec and proceed with simple outputs - -### Step 1.6: Define the Doc Spec (if needed) +**If detected**, offer to create a doc spec: +1. Inform the user: "This workflow produces a specific document type. I recommend defining a doc spec first." +2. Ask if they want to create a doc spec, use existing one, or skip -When creating a doc spec, gather the following information: +**If creating a doc spec**, gather: +- Document name and purpose +- Target audience and frequency +- Quality criteria (3-5, focused on the output document itself) +- Document structure (sections, required elements) -1. **Document Identity** - - What is the document called? (e.g., "Monthly AWS Spending Report") - - Brief description of its purpose - - Where should these documents be stored? (path patterns like `finance/aws-reports/*.md`) - -2. **Audience and Context** - - Who reads this document? (target audience) - - How often is it produced? (frequency) - -3. **Quality Criteria** (3-5 criteria, each with name and description) - - **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve. - - Examples for a spending report: - - **Visualization**: Must include charts showing spend breakdown by service - - **Variance Analysis**: Must compare current month against previous with percentages - - **Action Items**: Must include recommended cost optimization actions - - **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible. - -4. **Document Structure** - - What sections should it have? - - Any required elements (tables, charts, summaries)? - -### Step 1.7: Create the doc spec File (if needed) - -Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`: - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure. - -**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files). - -After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output. - -### Step 2: Define Each Step - -For each major phase they mentioned, ask structured questions to gather details: - -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? - - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output - - #### Work Product Storage Guidelines - - **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only. - - **Why this matters**: - - **Version control**: Work products in the main repo are tracked by git and visible in PRs - - **Discoverability**: Team members can find outputs without knowing about DeepWork internals - - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths - - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`) - - **Good output path patterns**: - ``` - competitive_research/competitors_list.md - competitive_research/acme_corp/research.md - operations/reports/2026-01/spending_analysis.md - docs/api/endpoints.md - ``` - - **Avoid these patterns**: - ``` - .deepwork/outputs/report.md # Hidden in dot-directory - output.md # Too generic, no context - research.md # Unclear which research - temp/draft.md # Transient-sounding paths - ``` - - **Organizing multi-file outputs**: - - Use the job name as a top-level folder when outputs are job-specific - - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/` - - Match existing project conventions when extending a codebase - - **When to include dates in paths**: - - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful. - ``` - operations/reports/2026-01/spending_analysis.md # Monthly report - keep history - hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf # Per-employee quarterly review - ``` - - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files. - ``` - competitive_research/acme_corp/swot.md # Current SWOT - updated over time - docs/architecture/overview.md # Living document - ``` - - **Supporting materials and intermediate outputs**: - - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output - - Name the dataroom folder by replacing the file extension with `_dataroom` - ``` - operations/reports/2026-01/spending_analysis.md # Final output - operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials - raw_data.csv - vendor_breakdown.md - notes.md - ``` - - This keeps supporting materials organized and discoverable without cluttering the main output location - -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? - -6. **Agent Delegation** (optional) - - Should this step be executed by a specific agent type? - - Use the `agent` field when the step should run in a forked context with a specific agent - - When `agent` is set, the generated skill automatically includes `context: fork` - - Available agent types: - - `general-purpose` - Standard agent for multi-step tasks - - ```yaml - steps: - - id: research_step - agent: general-purpose # Delegates to the general-purpose agent - ``` - -**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. - -#### Doc Spec-Aware Output Format - -When a step produces a document with a doc spec reference, use this format in job.yml: - -```yaml -outputs: - - file: reports/monthly_spending.md - doc_spec: .deepwork/doc_specs/monthly_aws_report.md -``` +Create at `.deepwork/doc_specs/[doc_spec_name].md`. Reference `.deepwork/doc_specs/job_spec.md` for an example. -The doc spec's quality criteria will automatically be included in the generated skill, ensuring consistent document quality. +### Phase 3: Define Each Step -### Capability Considerations +For each major phase, gather: -When defining steps, identify any that require specialized tools: +1. **Purpose** - What does this step accomplish? What are inputs and outputs? -**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. +2. **Inputs**: + - User-provided parameters (e.g., topic, target audience)? + - Files from previous steps? -### Step 3: Validate the Workflow +3. **Outputs**: + - What files does this step produce? + - Format (markdown, YAML, JSON)? + - Where to save? (Use meaningful paths like `competitive_research/analysis.md`, not `.deepwork/outputs/`) + - Does this output have a doc spec? -After gathering information about all steps: +4. **Dependencies** - Which previous steps must complete first? -1. **Review the flow** - - Summarize the complete workflow - - Show how outputs from one step feed into the next - - Ask if anything is missing +5. **Process** - Key activities? Quality checks needed? -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? +6. **Agent Delegation** - Should this step run via a specific agent? Use `agent: experts` for domain-specific expertise. -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) +#### Output Path Guidelines -### Step 4: Define Quality Validation (Stop Hooks) +- Place outputs in main repo, not dot-directories +- Use job name as top-level folder for job-specific outputs +- Include dates for periodic outputs that accumulate (monthly reports) +- Omit dates for current-state outputs that get updated in place +- Use `_dataroom` folders for supporting materials -For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. - -**Ask structured questions about quality validation:** -- "Are there specific quality criteria that must be met for this step?" -- "Would you like the agent to validate its work before completing?" -- "What would make you send the work back for revision?" - -**Stop hooks are particularly valuable for:** -- Steps with complex outputs that need multiple checks -- Steps where quality is critical (final deliverables) -- Steps with subjective quality criteria that benefit from AI self-review - -**Three types of stop hooks are supported:** - -1. **Inline Prompt** (`prompt`) - Best for simple quality criteria - ```yaml - stop_hooks: - - prompt: | - Verify the output meets these criteria: - 1. Contains at least 5 competitors - 2. Each competitor has a description - 3. Selection rationale is clear - ``` - -2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - -3. **Script** (`script`) - For programmatic validation (tests, linting) - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -**Multiple hooks can be combined:** -```yaml -stop_hooks: - - script: hooks/lint_output.sh - - prompt: "Verify the content is comprehensive and well-organized" -``` +### Phase 4: Validate the Workflow -**Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). +After gathering all step information: -### Step 5: Create the Job Directory and Specification +1. **Review the flow** - Summarize the complete workflow, show how outputs feed into next steps +2. **Check for gaps** - Undefined inputs? Unused outputs? Circular dependencies? +3. **Confirm details** - Job name (lowercase_underscores), summary (max 200 chars), description (detailed), version (1.0.0) -Only after you have complete understanding, create the job directory and `job.yml` file: +### Phase 5: Create the Job -**First, create the directory structure** using the `make_new_job.sh` script: +Create the directory structure: ```bash .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` -This creates: -- `.deepwork/jobs/[job_name]/` - Main job directory -- `.deepwork/jobs/[job_name]/steps/` - For step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts -- `.deepwork/jobs/[job_name]/templates/` - For example file formats -- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance - -**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) - -**Doc Spec**: See `.deepwork/doc_specs/job_spec.md` for the complete specification with quality criteria. - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. - -**Important**: -- Use lowercase with underscores for job name and step IDs -- Ensure file inputs reference steps in dependencies -- 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 -- Include a `changelog` section with an initial entry for version 1.0.0 - -## 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? +Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml`. -User: Yes, that's close. I would say: -1. Identify competitors -2. Research each one -3. Create comparison analysis -4. Write positioning recommendations +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for structure and `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a complete example. -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 in the project root, or in a subdirectory like `research/` or `data/`? - -User: Just call it `competitors_list.md` in the project root. - -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/jobs/competitive_research/job.yml with the complete spec] - -✓ Job specification created! - -**File created:** -- .deepwork/jobs/competitive_research/job.yml - -**Next step:** -Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria. -``` - -## Important Guidelines - -1. **Focus on specification only** - Don't create instruction files yet -2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool -3. **Rich context in description** - This helps with future refinement -4. **Validate understanding** - Summarize and confirm before creating -5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed - -## Validation Rules - -Before creating the job.yml, ensure: +**Validation rules**: - 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 +- Summary: under 200 characters +- Step IDs: unique, lowercase with underscores +- Dependencies must reference existing steps +- File inputs with `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 5 above). - -**Location**: `.deepwork/jobs/[job_name]/job.yml` -(Where `[job_name]` is the name of the new job being created) +## Output -After creating the file: -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.review_job_spec` next +**File**: `.deepwork/jobs/[job_name]/job.yml` +After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index 749c8c6f..6dbad31b 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -2,15 +2,15 @@ ## Objective -Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step. +Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification. ## Task -Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. +Read the `job.yml` specification and create all necessary files to make the job functional, then sync the commands. -### Step 1: Create Directory Structure Using Script +### Step 1: Create Directory Structure -Run the `make_new_job.sh` script to create the standard directory structure: +Run the `make_new_job.sh` script: ```bash .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] @@ -19,215 +19,85 @@ Run the `make_new_job.sh` script to create the standard directory structure: This creates: - `.deepwork/jobs/[job_name]/` - Main job directory - `.deepwork/jobs/[job_name]/steps/` - Step instruction files -- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) -- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - Example file formats - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance -**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: -```bash -mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates -touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep -``` +**Note**: If directory exists from define step, skip or just create missing subdirectories. ### Step 2: Read and Validate the Specification -1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec 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 +1. Read `.deepwork/jobs/[job_name]/job.yml` +2. Validate: name, version, summary, description, steps are present +3. Check dependencies reference existing steps, no circular dependencies +4. Verify file inputs match dependencies ### 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`. +For each step in job.yml, create `.deepwork/jobs/[job_name]/steps/[step_id].md`. -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. +**Reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for structure. -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. +**Guidelines**: -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- `job.yml.example` - Complete job specification example -- `step_instruction.md.example` - Complete step instruction example - -**Guidelines for generating instructions:** - -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 +1. **Use the job description** - It provides crucial context +2. **Be specific** - Tailor instructions to the step's purpose, not generic 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 -6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks -7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" - -### Handling Stop Hooks - -If a step in the job.yml has `stop_hooks` defined, the generated instruction file should: - -1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the stop hooks will validate -2. **Be explicit about success** - Help the agent understand when the step is truly complete -3. **Include the promise pattern** - Mention that `✓ Quality Criteria Met` should be included when criteria are met - -**Example: If the job.yml has:** -```yaml -- id: research_competitors - name: "Research Competitors" - stop_hooks: - - prompt: | - Verify the research meets criteria: - 1. Each competitor has at least 3 data points - 2. Sources are cited - 3. Information is current (within last year) -``` - -**The instruction file should include:** -```markdown -## Quality Criteria +4. **Explain the "why"** - Help understand the step's role in the workflow +5. **Ask structured questions** - Steps with user inputs MUST explicitly tell the agent to "ask structured questions" +6. **Align with hooks** - If step has `stop_hooks`, ensure quality criteria match the hooks -- Each competitor has at least 3 distinct data points -- All information is sourced with citations -- Data is current (from within the last year) -- When all criteria are met, include `✓ Quality Criteria Met` in your response -``` - -This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. - -### Using Supplementary Reference Files - -Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. - -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. +Each instruction file should include: +- **Objective** - What this step accomplishes +- **Task** - Detailed process +- **Output Format** - Examples of expected outputs +- **Quality Criteria** - How to verify completion ### Step 4: Verify job.yml Location -Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it. +Ensure `job.yml` is at `.deepwork/jobs/[job_name]/job.yml`. ### Step 5: Sync Skills -Run `deepwork sync` to generate the skills for this job: +Run: ```bash deepwork sync ``` -This will: -- Parse the job definition -- Generate skills for each step -- Make the skills available in `.claude/skills/` (or appropriate platform directory) - -### Step 6: Consider Rules for the New Job +This generates skills in `.claude/skills/` (or appropriate platform directory). -After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain. +### Step 6: Consider Rules -**What are rules?** +After implementing, consider whether **rules** would help this job's domain. -Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure: -- Documentation stays in sync with code +**What are rules?** Automated guardrails that trigger when certain files change, ensuring: +- Documentation stays in sync - Team guidelines are followed -- Architectural decisions are respected - Quality standards are maintained **When to suggest rules:** - -Think about the job you just implemented and ask: - Does this job produce outputs that other files depend on? -- Are there documentation files that should be updated when this job's outputs change? -- Are there quality checks or reviews that should happen when certain files in this domain change? -- Could changes to the job's output files impact other parts of the project? - -**Examples of rules that might make sense:** +- Are there docs that should update when outputs change? +- Could changes impact other parts of the project? +**Examples**: | Job Type | Potential Rule | |----------|----------------| | API Design | "Update API docs when endpoint definitions change" | -| Database Schema | "Review migrations when schema files change" | | Competitive Research | "Update strategy docs when competitor analysis changes" | | Feature Development | "Update changelog when feature files change" | -| Configuration Management | "Update install guide when config files change" | - -**How to offer rule creation:** - -If you identify one or more rules that would benefit the user, explain: -1. **What the rule would do** - What triggers it and what action it prompts -2. **Why it would help** - How it prevents common mistakes or keeps things in sync -3. **What files it would watch** - The trigger patterns - -Then ask the user: - -> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up." - -If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule. - -**Example dialogue:** - -``` -Based on the competitive_research job you just created, I noticed that when -competitor analysis files change, it would be helpful to remind you to update -your strategy documentation. - -I'd suggest a rule like: -- **Name**: "Update strategy when competitor analysis changes" -- **Trigger**: `**/positioning_report.md` -- **Action**: Prompt to review and update `docs/strategy.md` - -Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up. -``` - -**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense. - -## Example Implementation - -For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - -## Important Guidelines - -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 +If you identify helpful rules, explain what they would do and offer: "Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up." -Before running `deepwork sync`, verify: -- All directories exist -- `job.yml` is in place -- All step instruction files exist (one per step) -- No file system errors +**Note**: Not every job needs rules. Only suggest when genuinely helpful. ## 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 +- [ ] job.yml in correct location +- [ ] All step instruction files created (not stubs) +- [ ] Instructions are specific and actionable +- [ ] Output examples provided +- [ ] Quality criteria defined for each step - [ ] `deepwork sync` executed successfully -- [ ] Skills generated in platform directory -- [ ] Considered whether rules would benefit this job (Step 6) -- [ ] If rules suggested, offered to run `/deepwork_rules.define` - -## 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 -- Steps with user inputs explicitly use "ask structured questions" phrasing -- Sync completed successfully -- Skills available for use -- Thoughtfully considered relevant rules for the job domain +- [ ] Considered relevant rules for this job diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index bfb393a5..9b14ef06 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -2,354 +2,113 @@ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. +Reflect on the conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture run-specific learnings in AGENTS.md files. ## Task -Analyze the conversation history to extract learnings and improvements, then apply them appropriately: -- **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic +Analyze conversation history to extract learnings, then apply them: +- **Generalizable learnings** -> Update job instruction files +- **Bespoke learnings** (run-specific) -> Add to AGENTS.md in the working folder ### Step 1: Analyze Conversation for Job Executions -1. **Scan the conversation** for DeepWork slash commands that were run - - Look for patterns like `/job_name.step_id` - - Identify which jobs and steps were executed - - Note the order of execution +1. **Scan the conversation** for DeepWork slash commands (`/job_name.step_id`) +2. **Identify the target folder** - the deepest common folder for all work on the topic +3. **If no job specified**, ask which job to learn from -2. **Identify the target folder** - - This should be the deepest common folder that would contain all work on the topic in the future - - Should be clear from conversation history where work was done - - If unclear, run `git diff` to see where changes were made on the branch - -3. **If no job was specified**, ask the user: - - "Which DeepWork job would you like me to learn from?" - - List available jobs from `.deepwork/jobs/` - -### Step 2: Identify Points of Confusion and Inefficiency +### Step 2: Identify Confusion and Inefficiency Review the conversation for: -1. **Confusion signals** - - Questions the agent asked that shouldn't have been necessary - - Misunderstandings about what a step required - - Incorrect outputs that needed correction - - Ambiguous instructions that led to wrong interpretations +**Confusion signals**: +- Unnecessary questions the agent asked +- Misunderstandings about step requirements +- Incorrect outputs needing correction +- Ambiguous instructions causing wrong interpretations -2. **Inefficiency signals** - - Extra steps or iterations that were needed - - Information that had to be repeated - - Context that was missing from instructions - - Dependencies that weren't clear +**Inefficiency signals**: +- Extra iterations needed +- Repeated information +- Missing context +- Unclear dependencies -3. **Error patterns** - - Failed validations and why they failed - - Quality criteria that were misunderstood - - Edge cases that weren't handled +**Error patterns**: +- Failed validations and why +- Misunderstood quality criteria +- Unhandled edge cases -4. **Success patterns** - - What worked particularly well - - Efficient approaches worth preserving - - Good examples that could be added to instructions +**Success patterns**: +- What worked well +- Efficient approaches worth preserving +- Good examples to add to instructions ### Step 3: Classify Learnings -For each learning identified, determine if it is: +For each learning, determine if it is: -**Generalizable** (should improve instructions): +**Generalizable** (update instructions): - Would help ANY future run of this job - Addresses unclear or missing guidance -- Fixes incorrect assumptions in instructions -- Adds helpful examples or context -- Examples: - - "Step instructions should mention that X format is required" - - "Quality criteria should include checking for Y" - - "Add example of correct output format" - -**doc spec-Related** (should improve doc spec files): +- Fixes incorrect assumptions +- Adds helpful examples + +**Doc spec-related** (update doc spec files): - Improvements to document quality criteria - Changes to document structure or format -- Updated audience or frequency information -- Examples: - - "The report should include a summary table" - - "Quality criterion 'Visualization' needs clearer requirements" - - "Documents need a section for action items" -**Bespoke** (should go in AGENTS.md): +**Bespoke** (add to AGENTS.md): - Specific to THIS project/codebase/run -- Depends on local conventions or structure +- Depends on local conventions - References specific files or paths -- Would not apply to other uses of this job -- Examples: - - "In this codebase, API endpoints are in `src/api/`" - - "This project uses camelCase for function names" - - "The main config file is at `config/settings.yml`" - -### Step 3.5: Identify doc spec-Related Learnings - -Review the conversation for doc spec-related improvements: - -1. **Quality Criteria Changes** - - Were any quality criteria unclear or insufficient? - - Did the agent repeatedly fail certain criteria? - - Are there new criteria that should be added? - -2. **Document Structure Changes** - - Did the user request different sections? - - Were parts of the document format confusing? - - Should the example document be updated? - -3. **Metadata Updates** - - Has the target audience changed? - - Should frequency or path patterns be updated? - -**Signals for doc spec improvements:** -- User asked for changes to document format -- Repeated validation failures on specific criteria -- Feedback about missing sections or information -- Changes to how documents are organized/stored +- Would not apply to other uses -### Step 4: Update Job Instructions (Generalizable Learnings) +### Step 4: Update Job Instructions (Generalizable) For each generalizable learning: -1. **Locate the instruction file** - - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements** - - Add missing context or clarification +1. Locate `.deepwork/jobs/[job_name]/steps/[step_id].md` +2. Make targeted improvements: + - Add missing context - Include helpful examples - Clarify ambiguous instructions - - Update quality criteria if needed - -3. **Keep instructions concise** - - Avoid redundancy - don't repeat the same guidance in multiple places - - Be direct - remove verbose explanations that don't add value - - Prefer bullet points over paragraphs where appropriate - -4. **Preserve instruction structure** - - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - - Add to appropriate sections rather than restructuring - - Maintain consistency with other steps - -5. **Track changes for changelog** - - Note what was changed and why - - Prepare changelog entry for job.yml - -### Step 4b: Extract Shared Content into Referenced Files - -Review all instruction files for the job and identify content that: -- Appears in multiple step instructions (duplicated) -- Is lengthy and could be extracted for clarity -- Would benefit from being maintained in one place - -**Extract to shared files:** - -1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` - - `conventions.md` - Coding/formatting conventions used across steps - - `examples.md` - Common examples referenced by multiple steps - - `schemas.md` - Data structures or formats used throughout - -2. **Reference from instructions** using markdown includes or explicit references: - ```markdown - ## Conventions - - Follow the conventions defined in `shared/conventions.md`. - ``` - -3. **Benefits of extraction:** - - Single source of truth - update once, applies everywhere - - Shorter instruction files - easier to read and maintain - - Consistent guidance across steps - -### Step 4.5: Update doc spec Files (doc spec-Related Learnings) - -If doc spec-related learnings were identified: - -1. **Locate the doc spec file** - - Find doc spec references in job.yml outputs (look for `doc_spec: .deepwork/doc_specs/[doc_spec_name].md`) - - doc spec files are at `.deepwork/doc_specs/[doc_spec_name].md` - -2. **Update quality_criteria array** - - Add new criteria with name and description - - Modify existing criteria descriptions for clarity - - Remove criteria that are no longer relevant - -3. **Update example document** - - Modify the markdown body to reflect structure changes - - Ensure the example matches updated criteria - -4. **Update metadata as needed** - - target_audience: If audience has changed - - frequency: If production cadence has changed - - path_patterns: If storage location has changed - -**Example doc spec update:** -```yaml -# Before -quality_criteria: - - name: Visualization - description: Include charts - -# After -quality_criteria: - - name: Visualization - description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend -``` - -### Step 5: Create/Update AGENTS.md (Bespoke Learnings) - -The AGENTS.md file captures project-specific knowledge that helps future agent runs. - -1. **Determine the correct location** - - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - - This ensures the knowledge is available when working in that context - - If uncertain, place at the project root - -2. **Use file references where possible** - - Instead of duplicating information, reference source files - - This keeps AGENTS.md in sync as the codebase evolves - - Pattern: "See `path/to/file.ext` for [description]" + - Update quality criteria +3. Keep instructions concise - avoid redundancy +4. Preserve structure (Objective, Task, Output Format, Quality Criteria) -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. +### Step 5: Update Doc Specs (if applicable) -4. **Writing entries** - - Be concise but specific - - Always prefer file references over inline content - - Use line numbers when referencing specific code: `file.ext:42` - - Group related learnings together +If doc spec-related learnings identified: -### Step 6: Update Job Version and Changelog +1. Locate doc spec at `.deepwork/doc_specs/[doc_spec_name].md` +2. Update quality_criteria, example document, or metadata as needed -If instruction files were modified: +### Step 6: Create/Update AGENTS.md (Bespoke) -1. **Bump version in job.yml** - - Patch version (0.0.x) for instruction improvements - - Minor version (0.x.0) if quality criteria changed +1. Place in the deepest common folder for the topic +2. Use file references instead of duplicating content: "See `path/to/file.ext` for [description]" +3. Follow structure in `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` -2. **Add changelog entry** - ```yaml - - version: "[new_version]" - changes: "Improved [step] instructions based on execution learnings: [brief description]" - ``` - -### Step 7: Sync Skills - -**Run deepwork sync** (if instructions were modified) -```bash -deepwork sync -``` - -## File Reference Patterns - -When adding entries to AGENTS.md, prefer these patterns: - -**Good (references)**: +**Good patterns** (references): ```markdown - API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` - Configuration schema: Defined in `config/schema.json` ``` -**Avoid (duplicating)**: +**Avoid** (duplicating): ```markdown - API endpoints should return JSON with this format: { status: ..., data: ... } -- Error handling should use try/catch with custom error classes -- Configuration requires these fields: name, version, ... ``` -## Quality Criteria - -- Conversation has been analyzed for job executions -- Points of confusion and inefficiency are identified -- Learnings are correctly classified (generalizable vs bespoke) -- Job instructions updated for generalizable improvements -- Instructions are concise - no redundancy or unnecessary verbosity -- Shared/lengthy content extracted into referenced files where appropriate -- AGENTS.md created/updated with bespoke learnings -- File references used instead of duplicating content -- AGENTS.md is in the correct folder (the deepest common folder for the topic) -- When all criteria are met, include `✓ Quality Criteria Met` - -## Example Dialog - -``` -User: /deepwork_jobs.learn - -Claude: I'll analyze this conversation for learnings from DeepWork job executions. - -**Conversation Analysis** - -I found the following job executions: -1. `/competitive_research.identify_competitors` - Completed -2. `/competitive_research.research_competitors` - Completed with 2 iterations -3. `/competitive_research.comparative_analysis` - Completed - -**Identified Issues** - -1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. - -2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. - -**Classification** - -- Generalizable: Add pricing to research requirements in instructions -- Bespoke: This project focuses on B2B SaaS in the HR tech space - -**Actions Taken** - -1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: - - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements - - Added note about carrying forward industry context from previous step - -2. Created `./competitive_research_output/AGENTS.md`: - ```markdown - # Project Context for Competitive Research - - ## Job-Specific Context - - ### competitive_research - - #### Industry Focus - - Domain: B2B SaaS, HR Technology sector - - See `identify_competitors_output.md` for market definition - - #### Competitors Identified - - Reference: `competitor_list.md` for full details - - ## Last Updated - - Date: 2024-01-15 - - From conversation about: Initial competitive analysis run - ``` - -3. Updated job.yml version to 1.0.1 with changelog entry - -4. Ran `deepwork sync` - -**Summary** - -Updated job instructions and created AGENTS.md with bespoke learnings. -``` - -## Handling Edge Cases - -**No job executions found**: -- Ask user which job they'd like to analyze -- Or offer to review available jobs +### Step 7: Update Job Version and Sync -**Multiple jobs executed**: -- Analyze each job separately -- Create separate AGENTS.md entries or files as appropriate +If instructions were modified: -**AGENTS.md already exists**: -- Read existing content -- Append new learnings to appropriate sections -- Update "Last Updated" section +1. Bump version in job.yml (patch for improvements, minor for quality criteria changes) +2. Add changelog entry +3. Run `deepwork sync` -**No issues found**: -- Document what worked well -- Consider if any successful patterns should be added to instructions as examples +## Output -**Sensitive information**: -- Never include secrets, credentials, or PII in AGENTS.md -- Reference config files instead of including values +- Updated job instructions (generalizable learnings) +- Updated doc specs (if applicable) +- AGENTS.md with bespoke learnings in the correct working folder diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md index fcc0ae9c..7261fe9d 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md @@ -2,207 +2,77 @@ ## Objective -Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass. +Review the `job.yml` created in the define step against doc spec quality criteria, then iterate on fixes until all criteria pass. ## Why This Step Exists -The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process. +The define step focuses on understanding user requirements. This review step ensures the specification meets quality standards before implementation. A fresh review catches issues that might be missed after being deeply involved in definition. ## Task -Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass. +Review the job.yml against all 9 doc spec quality criteria, fix any failures, and repeat until all pass. -### Step 1: Read the Job Specification - -Read the `job.yml` file created in the define step: +### Step 1: Read the Files +Read the job specification: ``` .deepwork/jobs/[job_name]/job.yml ``` -Also read the doc spec for reference: - +Read the doc spec for reference: ``` .deepwork/doc_specs/job_spec.md ``` -### Step 2: Spawn Review Sub-Agent - -Use the Task tool to spawn a sub-agent that will provide an unbiased review: - -``` -Task tool parameters: -- subagent_type: "general-purpose" -- model: "haiku" -- description: "Review job.yml against doc spec" -- prompt: [see below] -``` - -**Sub-agent prompt template:** - -``` -Review this job.yml against the following 9 quality criteria from the doc spec. - -For each criterion, respond with: -- PASS or FAIL -- If FAIL: specific issue and suggested fix - -## job.yml Content - -[paste the full job.yml content here] - -## Quality Criteria - -1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`) - -2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`) - -3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes - -4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users - -5. **Changelog Present**: Must include a changelog array with at least the initial version entry - -6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array - -7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references - -8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array - -9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`) - -## Response Format - -Respond with a structured evaluation: - -### Overall: [X/9 PASS] - -### Criterion Results - -1. Valid Identifier: [PASS/FAIL] - [If FAIL: Issue and fix] - -2. Semantic Version: [PASS/FAIL] - [If FAIL: Issue and fix] - -[... continue for all 9 criteria ...] - -### Summary of Required Fixes - -[List any fixes needed, or "No fixes required - all criteria pass"] -``` - -### Step 3: Review Sub-Agent Findings +### Step 2: Evaluate Against Quality Criteria -Parse the sub-agent's response: +Review the job.yml against these 9 criteria: -1. **Count passing criteria** - How many of the 9 criteria passed? -2. **Identify failures** - List specific criteria that failed -3. **Note suggested fixes** - What changes does the sub-agent recommend? +1. **Valid Identifier** - Job name is lowercase with underscores, no spaces or special characters +2. **Semantic Version** - Version follows X.Y.Z format (e.g., `1.0.0`) +3. **Concise Summary** - Summary is under 200 characters and clearly describes the job +4. **Rich Description** - Description is multi-line and explains: problem solved, process, expected outcomes, target users +5. **Changelog Present** - Includes changelog array with at least initial version entry +6. **Complete Steps** - Each step has: id, name, description, instructions_file, outputs, dependencies +7. **Valid Dependencies** - Dependencies reference existing step IDs with no circular references +8. **Input Consistency** - File inputs with `from_step` reference a step in the dependencies array +9. **Output Paths** - Outputs are valid filenames or paths -### Step 4: Fix Failed Criteria +For each criterion, determine PASS or FAIL. If FAIL, note the specific issue and fix. -For each failed criterion, edit the job.yml to address the issue: +### Step 3: Fix Failed Criteria -**Common fixes by criterion:** +For each failed criterion, edit the job.yml: | Criterion | Common Issue | Fix | |-----------|-------------|-----| | Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores | -| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format | -| Concise Summary | Too long or vague | Shorten to <200 chars, be specific | -| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users | -| Changelog Present | Missing changelog | Add `changelog:` with initial version entry | -| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies | -| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies | -| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array | -| Output Paths | Invalid characters or format | Use valid filename/path format | +| Semantic Version | Invalid format | Set to `"1.0.0"` | +| Concise Summary | Too long | Shorten to <200 chars | +| Rich Description | Single line | Add multi-line explanation | +| Changelog Present | Missing | Add changelog with initial version | +| Complete Steps | Missing fields | Add required fields | +| Valid Dependencies | Non-existent step | Fix step ID reference | +| Input Consistency | from_step not in deps | Add step to dependencies | +| Output Paths | Invalid format | Use valid filename/path | -### Step 5: Re-Run Review (If Needed) +### Step 4: Re-Evaluate (If Needed) If any criteria failed: +1. Review the updated job.yml +2. Re-evaluate all criteria +3. Fix remaining issues +4. Repeat until all 9 pass -1. **Spawn a new sub-agent** with the updated job.yml content -2. **Review the new findings** -3. **Fix any remaining issues** -4. **Repeat until all 9 criteria pass** - -### Step 6: Confirm Completion +### Step 5: Confirm Completion When all 9 criteria pass: -1. **Announce success**: "All 9 doc spec quality criteria pass." -2. **List what was validated**: - - Valid Identifier - - Semantic Version - - Concise Summary - - Rich Description - - Changelog Present - - Complete Steps - - Valid Dependencies - - Input Consistency - - Output Paths -3. **Include the promise**: `Quality Criteria Met` -4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files." - -## Example Review Cycle - -``` -Claude: Let me review the job.yml against the doc spec quality criteria. - -[Spawns sub-agent with haiku model] - -Sub-agent response: -### Overall: 7/9 PASS - -### Criterion Results -1. Valid Identifier: PASS -2. Semantic Version: PASS -3. Concise Summary: FAIL - Issue: Summary is 245 characters, exceeds 200 char limit - Fix: Shorten to "Competitive analysis workflow for product positioning" -4. Rich Description: PASS -5. Changelog Present: FAIL - Issue: No changelog array present - Fix: Add changelog with initial version entry -6. Complete Steps: PASS -7. Valid Dependencies: PASS -8. Input Consistency: PASS -9. Output Paths: PASS - -### Summary of Required Fixes -1. Shorten summary to under 200 characters -2. Add changelog array with initial version - -Claude: I found 2 issues. Let me fix them. - -[Edits job.yml to shorten summary and add changelog] - -Claude: Let me verify the fixes with another review. - -[Spawns new sub-agent] - -Sub-agent response: -### Overall: 9/9 PASS - -### Summary of Required Fixes -No fixes required - all criteria pass - -Claude: All 9 doc spec quality criteria pass. - -Quality Criteria Met - -**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files. -``` - -## Quality Criteria - -- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review) -- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec -- **Findings Addressed**: All failed criteria were fixed by the main agent -- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed -- **Promise Included**: The response includes `Quality Criteria Met` when complete +1. Announce: "All 9 doc spec quality criteria pass." +2. List what was validated +3. Include: `Quality Criteria Met` +4. Guide to next step: "Run `/deepwork_jobs.implement` to generate the step instruction files." ## Output -The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria. +The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 quality criteria.