diff --git a/.claude/skills/add_platform.add_capabilities/SKILL.md b/.claude/skills/add_platform.add_capabilities/SKILL.md index 7dd71e27..abd28286 100644 --- a/.claude/skills/add_platform.add_capabilities/SKILL.md +++ b/.claude/skills/add_platform.add_capabilities/SKILL.md @@ -4,7 +4,9 @@ description: "Updates job schema and adapters with any new hook events the platf # add_platform.add_capabilities -**Step 2/4** in **add_platform** workflow +**Step 2/4** in **integrate** workflow + +> Full workflow to integrate a new AI platform into DeepWork > Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools. @@ -158,7 +160,7 @@ When you find a new hook type, consider whether it maps to an existing pattern o A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates @@ -203,7 +205,7 @@ Use branch format: `deepwork/add_platform-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 2/4 complete, outputs: job_schema.py, adapters.py" +2. Inform user: "integrate step 2/4 complete, outputs: job_schema.py, adapters.py" 3. **Continue workflow**: Use Skill tool to invoke `/add_platform.implement` --- diff --git a/.claude/skills/add_platform.implement/SKILL.md b/.claude/skills/add_platform.implement/SKILL.md index 167a6d7e..a9e5ae6a 100644 --- a/.claude/skills/add_platform.implement/SKILL.md +++ b/.claude/skills/add_platform.implement/SKILL.md @@ -8,7 +8,9 @@ description: "Creates platform adapter, templates, tests with 100% coverage, and # add_platform.implement -**Step 3/4** in **add_platform** workflow +**Step 3/4** in **integrate** workflow + +> Full workflow to integrate a new AI platform into DeepWork > Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools. @@ -254,7 +256,7 @@ The templates use Jinja2 and should produce files that match exactly what the pl A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates @@ -303,7 +305,7 @@ Use branch format: `deepwork/add_platform-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 3/4 complete, outputs: templates/, tests/, README.md" +2. Inform user: "integrate step 3/4 complete, outputs: templates/, tests/, README.md" 3. **Continue workflow**: Use Skill tool to invoke `/add_platform.verify` --- diff --git a/.claude/skills/add_platform.research/SKILL.md b/.claude/skills/add_platform.research/SKILL.md index 3a3e3604..4da84aa5 100644 --- a/.claude/skills/add_platform.research/SKILL.md +++ b/.claude/skills/add_platform.research/SKILL.md @@ -4,7 +4,9 @@ description: "Captures CLI configuration and hooks system documentation for the # add_platform.research -**Step 1/4** in **add_platform** workflow +**Step 1/4** in **integrate** workflow + +> Full workflow to integrate a new AI platform into DeepWork > Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools. @@ -207,7 +209,7 @@ Take time to be thorough - incomplete documentation will slow down subsequent st A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates @@ -252,7 +254,7 @@ Use branch format: `deepwork/add_platform-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 1/4 complete, outputs: cli_configuration.md, hooks_system.md" +2. Inform user: "integrate step 1/4 complete, outputs: cli_configuration.md, hooks_system.md" 3. **Continue workflow**: Use Skill tool to invoke `/add_platform.add_capabilities` --- diff --git a/.claude/skills/add_platform.verify/SKILL.md b/.claude/skills/add_platform.verify/SKILL.md index 605d92c4..72cd3467 100644 --- a/.claude/skills/add_platform.verify/SKILL.md +++ b/.claude/skills/add_platform.verify/SKILL.md @@ -4,7 +4,9 @@ description: "Sets up platform directories and verifies deepwork install works c # add_platform.verify -**Step 4/4** in **add_platform** workflow +**Step 4/4** in **integrate** workflow + +> Full workflow to integrate a new AI platform into DeepWork > Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools. @@ -134,7 +136,7 @@ Take time to verify each aspect - finding issues now is much better than having A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates @@ -178,8 +180,8 @@ Use branch format: `deepwork/add_platform-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 4/4 complete, outputs: verification_checklist.md" -3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. +2. Inform user: "integrate step 4/4 complete, outputs: verification_checklist.md" +3. **integrate workflow complete**: All steps finished. Consider creating a PR to merge the work branch. --- diff --git a/.claude/skills/add_platform/SKILL.md b/.claude/skills/add_platform/SKILL.md index 75aa7f05..474bb3a8 100644 --- a/.claude/skills/add_platform/SKILL.md +++ b/.claude/skills/add_platform/SKILL.md @@ -5,13 +5,13 @@ description: "Adds a new AI platform to DeepWork with adapter, templates, and te # add_platform -**Multi-step workflow**: Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools. +Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools. > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates @@ -27,22 +27,27 @@ comprehensive test coverage for new functionality. - Installation verification confirms the platform integrates correctly with existing jobs -## Available Steps +## Workflows +### integrate + +Full workflow to integrate a new AI platform into DeepWork + +**Steps in order**: 1. **research** - Captures CLI configuration and hooks system documentation for the new platform. Use when starting platform integration. -2. **add_capabilities** - Updates job schema and adapters with any new hook events the platform supports. Use after research to extend DeepWork's hook system. (requires: research) -3. **implement** - Creates platform adapter, templates, tests with 100% coverage, and README documentation. Use after adding hook capabilities. (requires: research, add_capabilities) -4. **verify** - Sets up platform directories and verifies deepwork install works correctly. Use after implementation to confirm integration. (requires: implement) +2. **add_capabilities** - Updates job schema and adapters with any new hook events the platform supports. Use after research to extend DeepWork's hook system. +3. **implement** - Creates platform adapter, templates, tests with 100% coverage, and README documentation. Use after adding hook capabilities. +4. **verify** - Sets up platform directories and verifies deepwork install works correctly. Use after implementation to confirm integration. + +**Start workflow**: `/add_platform.research` + ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/add_platform` to determine user intent: -- "research" or related terms → start at `add_platform.research` -- "add_capabilities" or related terms → start at `add_platform.add_capabilities` -- "implement" or related terms → start at `add_platform.implement` -- "verify" or related terms → start at `add_platform.verify` +- "integrate" or related terms → start integrate workflow at `add_platform.research` ### Step 2: Invoke Starting Step @@ -54,20 +59,22 @@ Skill tool: add_platform.research ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: -- Present available steps as numbered options +- Present available workflows and standalone skills as options - Let user select the starting point ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/.claude/skills/commit.commit_and_push/SKILL.md b/.claude/skills/commit.commit_and_push/SKILL.md index 779c6e52..3ecf236e 100644 --- a/.claude/skills/commit.commit_and_push/SKILL.md +++ b/.claude/skills/commit.commit_and_push/SKILL.md @@ -4,7 +4,9 @@ description: "Verifies changed files, creates commit, and pushes to remote. Use # commit.commit_and_push -**Step 4/4** in **commit** workflow +**Step 4/4** in **full** workflow + +> Full commit workflow: review, test, lint, and commit > Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks. @@ -115,7 +117,7 @@ This is the final step of the commit workflow. The agent verifies that the chang A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. @@ -150,8 +152,8 @@ Use branch format: `deepwork/commit-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 4/4 complete, outputs: changes_committed" -3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. +2. Inform user: "full step 4/4 complete, outputs: changes_committed" +3. **full workflow complete**: All steps finished. Consider creating a PR to merge the work branch. --- diff --git a/.claude/skills/commit.lint/SKILL.md b/.claude/skills/commit.lint/SKILL.md index 8bedb8b5..9cce8111 100644 --- a/.claude/skills/commit.lint/SKILL.md +++ b/.claude/skills/commit.lint/SKILL.md @@ -4,7 +4,9 @@ description: "Formats and lints code with ruff using a sub-agent. Use after test # commit.lint -**Step 3/4** in **commit** workflow +**Step 3/4** in **full** workflow + +> Full commit workflow: review, test, lint, and commit > Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks. @@ -95,7 +97,7 @@ This step ensures code quality and consistency before committing. It runs after A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. @@ -130,7 +132,7 @@ Use branch format: `deepwork/commit-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 3/4 complete, outputs: code_formatted" +2. Inform user: "full step 3/4 complete, outputs: code_formatted" 3. **Continue workflow**: Use Skill tool to invoke `/commit.commit_and_push` --- diff --git a/.claude/skills/commit.review/SKILL.md b/.claude/skills/commit.review/SKILL.md index 71d4c6b3..fa2a1119 100644 --- a/.claude/skills/commit.review/SKILL.md +++ b/.claude/skills/commit.review/SKILL.md @@ -4,7 +4,9 @@ description: "Reviews changed code for issues, DRY opportunities, naming clarity # commit.review -**Step 1/4** in **commit** workflow +**Step 1/4** in **full** workflow + +> Full commit workflow: review, test, lint, and commit > Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks. @@ -124,7 +126,7 @@ This is the first step of the commit workflow. Code review happens before tests A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. @@ -159,7 +161,7 @@ Use branch format: `deepwork/commit-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 1/4 complete, outputs: code_reviewed" +2. Inform user: "full step 1/4 complete, outputs: code_reviewed" 3. **Continue workflow**: Use Skill tool to invoke `/commit.test` --- diff --git a/.claude/skills/commit.test/SKILL.md b/.claude/skills/commit.test/SKILL.md index cef6a52a..bdb19156 100644 --- a/.claude/skills/commit.test/SKILL.md +++ b/.claude/skills/commit.test/SKILL.md @@ -4,7 +4,9 @@ description: "Pulls latest code and runs tests until all pass. Use after code re # commit.test -**Step 2/4** in **commit** workflow +**Step 2/4** in **full** workflow + +> Full commit workflow: review, test, lint, and commit > Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks. @@ -76,7 +78,7 @@ This step runs after code review. Tests must pass before proceeding to lint and A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. @@ -116,7 +118,7 @@ Use branch format: `deepwork/commit-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 2/4 complete, outputs: tests_passing" +2. Inform user: "full step 2/4 complete, outputs: tests_passing" 3. **Continue workflow**: Use Skill tool to invoke `/commit.lint` --- diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md index 9570a883..3839ffbd 100644 --- a/.claude/skills/commit/SKILL.md +++ b/.claude/skills/commit/SKILL.md @@ -5,13 +5,13 @@ description: "Reviews code, runs tests, lints, and commits changes. Use when rea # commit -**Multi-step workflow**: Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks. +Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks. > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. @@ -23,22 +23,27 @@ Steps: 4. commit_and_push - Review changes and commit/push -## Available Steps +## Workflows +### full + +Full commit workflow: review, test, lint, and commit + +**Steps in order**: 1. **review** - Reviews changed code for issues, DRY opportunities, naming clarity, and test coverage using a sub-agent. Use as the first step before testing. -2. **test** - Pulls latest code and runs tests until all pass. Use after code review passes to verify changes work correctly. (requires: review) -3. **lint** - Formats and lints code with ruff using a sub-agent. Use after tests pass to ensure code style compliance. (requires: test) -4. **commit_and_push** - Verifies changed files, creates commit, and pushes to remote. Use after linting passes to finalize changes. (requires: lint) +2. **test** - Pulls latest code and runs tests until all pass. Use after code review passes to verify changes work correctly. +3. **lint** - Formats and lints code with ruff using a sub-agent. Use after tests pass to ensure code style compliance. +4. **commit_and_push** - Verifies changed files, creates commit, and pushes to remote. Use after linting passes to finalize changes. + +**Start workflow**: `/commit.review` + ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/commit` to determine user intent: -- "review" or related terms → start at `commit.review` -- "test" or related terms → start at `commit.test` -- "lint" or related terms → start at `commit.lint` -- "commit_and_push" or related terms → start at `commit.commit_and_push` +- "full" or related terms → start full workflow at `commit.review` ### Step 2: Invoke Starting Step @@ -50,20 +55,22 @@ Skill tool: commit.review ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: -- Present available steps as numbered options +- Present available workflows and standalone skills as options - Let user select the starting point ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index ef5b2407..f0564f5a 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -4,7 +4,9 @@ description: "Creates a job.yml specification by gathering workflow requirements # deepwork_jobs.define -**Step 1/4** in **deepwork_jobs** workflow +**Step 1/3** in **new_job** workflow + +> Create a new DeepWork job from scratch through definition, review, and implementation > Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. @@ -417,11 +419,11 @@ After creating the file: Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -663,7 +665,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 1/4 complete, outputs: job.yml" +2. Inform user: "new_job step 1/3 complete, outputs: job.yml" 3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.review_job_spec` --- diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index 03879aa2..6efc5bc8 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -4,7 +4,9 @@ description: "Generates step instruction files and syncs slash commands from the # deepwork_jobs.implement -**Step 3/4** in **deepwork_jobs** workflow +**Step 3/3** in **new_job** workflow + +> Create a new DeepWork job from scratch through definition, review, and implementation > Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. @@ -262,11 +264,11 @@ Before marking this step complete, ensure: Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -322,8 +324,8 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 3/4 complete, outputs: steps/" -3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.learn` +2. Inform user: "new_job step 3/3 complete, outputs: steps/" +3. **new_job workflow complete**: All steps finished. Consider creating a PR to merge the work branch. --- diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index d50ab9af..265b5d95 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -377,11 +377,11 @@ Updated job instructions and created AGENTS.md with bespoke learnings. To get th Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 4e54318a..ecf8d927 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -4,7 +4,9 @@ description: "Reviews job.yml against quality criteria using a sub-agent for unb # deepwork_jobs.review_job_spec -**Step 2/4** in **deepwork_jobs** workflow +**Step 2/3** in **new_job** workflow + +> Create a new DeepWork job from scratch through definition, review, and implementation > Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. @@ -232,11 +234,11 @@ The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -470,7 +472,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 2/4 complete, outputs: job.yml" +2. Inform user: "new_job step 2/3 complete, outputs: job.yml" 3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.implement` --- diff --git a/.claude/skills/deepwork_jobs/SKILL.md b/.claude/skills/deepwork_jobs/SKILL.md index 00f2bb48..ec2526f5 100644 --- a/.claude/skills/deepwork_jobs/SKILL.md +++ b/.claude/skills/deepwork_jobs/SKILL.md @@ -5,38 +5,50 @@ description: "Creates and manages multi-step AI workflows. Use when defining, im # deepwork_jobs -**Multi-step workflow**: Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. +Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. -## Available Steps +## Workflows +### new_job + +Create a new DeepWork job from scratch through definition, review, and implementation + +**Steps in order**: 1. **define** - Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow. -2. **review_job_spec** - Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification. (requires: define) -3. **implement** - Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes. (requires: review_job_spec) -4. **learn** - Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it. +2. **review_job_spec** - Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification. +3. **implement** - Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes. + +**Start workflow**: `/deepwork_jobs.define` + +## Standalone Skills + +These skills can be run independently at any time: + +- **learn** - Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it. + Command: `/deepwork_jobs.learn` + ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/deepwork_jobs` to determine user intent: -- "define" or related terms → start at `deepwork_jobs.define` -- "review_job_spec" or related terms → start at `deepwork_jobs.review_job_spec` -- "implement" or related terms → start at `deepwork_jobs.implement` -- "learn" or related terms → start at `deepwork_jobs.learn` +- "new_job" or related terms → start new_job workflow at `deepwork_jobs.define` +- "learn" or related terms → run standalone skill `deepwork_jobs.learn` ### Step 2: Invoke Starting Step @@ -48,20 +60,22 @@ Skill tool: deepwork_jobs.define ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: -- Present available steps as numbered options +- Present available workflows and standalone skills as options - Let user select the starting point ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/.claude/skills/deepwork_rules/SKILL.md b/.claude/skills/deepwork_rules/SKILL.md index cfc42720..3de565a9 100644 --- a/.claude/skills/deepwork_rules/SKILL.md +++ b/.claude/skills/deepwork_rules/SKILL.md @@ -5,7 +5,7 @@ description: "Creates file-change rules that enforce guidelines during AI sessio # deepwork_rules -**Multi-step workflow**: Creates file-change rules that enforce guidelines during AI sessions. Use when automating documentation sync or code review triggers. +Creates file-change rules that enforce guidelines during AI sessions. Use when automating documentation sync or code review triggers. > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. @@ -34,16 +34,20 @@ Example use cases: - Auto-run `uv sync` when pyproject.toml changes (command action) -## Available Steps +## Standalone Skills + +These skills can be run independently at any time: + +- **define** - Creates a rule file that triggers when specified files change. Use when setting up documentation sync, code review requirements, or automated commands. + Command: `/deepwork_rules.define` -1. **define** - Creates a rule file that triggers when specified files change. Use when setting up documentation sync, code review requirements, or automated commands. ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/deepwork_rules` to determine user intent: -- "define" or related terms → start at `deepwork_rules.define` +- "define" or related terms → run standalone skill `deepwork_rules.define` ### Step 2: Invoke Starting Step @@ -55,10 +59,12 @@ Skill tool: deepwork_rules.define ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: @@ -68,7 +74,7 @@ If user intent is unclear, use AskUserQuestion to clarify: ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/.claude/skills/manual_tests.infinite_block_tests/SKILL.md b/.claude/skills/manual_tests.infinite_block_tests/SKILL.md index 5b3cb4b5..c6601a20 100644 --- a/.claude/skills/manual_tests.infinite_block_tests/SKILL.md +++ b/.claude/skills/manual_tests.infinite_block_tests/SKILL.md @@ -4,7 +4,9 @@ description: "Runs all 4 infinite block tests serially. Tests both 'should fire' # manual_tests.infinite_block_tests -**Step 4/4** in **manual_tests** workflow +**Step 4/4** in **run_all** workflow + +> Run all manual tests: reset, NOT-fire tests, fire tests, and infinite block tests > Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly. @@ -159,7 +161,7 @@ This step runs after both the "should NOT fire" and "should fire" test steps. It A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes @@ -240,8 +242,8 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 4/4 complete, outputs: infinite_block_results" -3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. +2. Inform user: "run_all step 4/4 complete, outputs: infinite_block_results" +3. **run_all workflow complete**: All steps finished. Consider creating a PR to merge the work branch. --- diff --git a/.claude/skills/manual_tests.reset/SKILL.md b/.claude/skills/manual_tests.reset/SKILL.md index 1792ef69..c08db344 100644 --- a/.claude/skills/manual_tests.reset/SKILL.md +++ b/.claude/skills/manual_tests.reset/SKILL.md @@ -4,7 +4,9 @@ description: "Runs FIRST to ensure clean environment. Also called internally by # manual_tests.reset -**Step 1/4** in **manual_tests** workflow +**Step 1/4** in **run_all** workflow + +> Run all manual tests: reset, NOT-fire tests, fire tests, and infinite block tests > Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly. @@ -57,7 +59,7 @@ deepwork rules clear_queue A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes @@ -130,7 +132,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 1/4 complete, outputs: clean_environment" +2. Inform user: "run_all step 1/4 complete, outputs: clean_environment" 3. **Continue workflow**: Use Skill tool to invoke `/manual_tests.run_not_fire_tests` --- diff --git a/.claude/skills/manual_tests.run_fire_tests/SKILL.md b/.claude/skills/manual_tests.run_fire_tests/SKILL.md index 29199317..43e147b7 100644 --- a/.claude/skills/manual_tests.run_fire_tests/SKILL.md +++ b/.claude/skills/manual_tests.run_fire_tests/SKILL.md @@ -4,7 +4,9 @@ description: "Runs all 6 'should fire' tests serially with resets between each. # manual_tests.run_fire_tests -**Step 3/4** in **manual_tests** workflow +**Step 3/4** in **run_all** workflow + +> Run all manual tests: reset, NOT-fire tests, fire tests, and infinite block tests > Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly. @@ -155,7 +157,7 @@ This step runs after the "should NOT fire" tests. These tests verify that rules A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes @@ -239,7 +241,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 3/4 complete, outputs: fire_results" +2. Inform user: "run_all step 3/4 complete, outputs: fire_results" 3. **Continue workflow**: Use Skill tool to invoke `/manual_tests.infinite_block_tests` --- diff --git a/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md b/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md index 65c3c899..6711e751 100644 --- a/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md +++ b/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md @@ -4,7 +4,9 @@ description: "Runs all 6 'should NOT fire' tests in parallel sub-agents. Use to # manual_tests.run_not_fire_tests -**Step 2/4** in **manual_tests** workflow +**Step 2/4** in **run_all** workflow + +> Run all manual tests: reset, NOT-fire tests, fire tests, and infinite block tests > Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly. @@ -141,7 +143,7 @@ This step runs after the reset step (which ensures a clean environment) and test A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes @@ -225,7 +227,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria: ## On Completion 1. Verify outputs are created -2. Inform user: "Step 2/4 complete, outputs: not_fire_results" +2. Inform user: "run_all step 2/4 complete, outputs: not_fire_results" 3. **Continue workflow**: Use Skill tool to invoke `/manual_tests.run_fire_tests` --- diff --git a/.claude/skills/manual_tests/SKILL.md b/.claude/skills/manual_tests/SKILL.md index 94e3b0ad..59b53adc 100644 --- a/.claude/skills/manual_tests/SKILL.md +++ b/.claude/skills/manual_tests/SKILL.md @@ -5,13 +5,13 @@ description: "Runs all manual hook/rule tests using sub-agents. Use when validat # manual_tests -**Multi-step workflow**: Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly. +Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly. > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes @@ -46,22 +46,27 @@ Test types covered: - Created mode (new files only) -## Available Steps +## Workflows +### run_all + +Run all manual tests: reset, NOT-fire tests, fire tests, and infinite block tests + +**Steps in order**: 1. **reset** - Runs FIRST to ensure clean environment. Also called internally by other steps when they need to revert changes and clear the queue. -2. **run_not_fire_tests** - Runs all 6 'should NOT fire' tests in parallel sub-agents. Use to verify rules don't fire when safety conditions are met. (requires: reset) -3. **run_fire_tests** - Runs all 6 'should fire' tests serially with resets between each. Use after NOT-fire tests to verify rules fire correctly. (requires: run_not_fire_tests) -4. **infinite_block_tests** - Runs all 4 infinite block tests serially. Tests both 'should fire' (no promise) and 'should NOT fire' (with promise) scenarios. (requires: run_fire_tests) +2. **run_not_fire_tests** - Runs all 6 'should NOT fire' tests in parallel sub-agents. Use to verify rules don't fire when safety conditions are met. +3. **run_fire_tests** - Runs all 6 'should fire' tests serially with resets between each. Use after NOT-fire tests to verify rules fire correctly. +4. **infinite_block_tests** - Runs all 4 infinite block tests serially. Tests both 'should fire' (no promise) and 'should NOT fire' (with promise) scenarios. + +**Start workflow**: `/manual_tests.reset` + ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/manual_tests` to determine user intent: -- "reset" or related terms → start at `manual_tests.reset` -- "run_not_fire_tests" or related terms → start at `manual_tests.run_not_fire_tests` -- "run_fire_tests" or related terms → start at `manual_tests.run_fire_tests` -- "infinite_block_tests" or related terms → start at `manual_tests.infinite_block_tests` +- "run_all" or related terms → start run_all workflow at `manual_tests.reset` ### Step 2: Invoke Starting Step @@ -73,20 +78,22 @@ Skill tool: manual_tests.reset ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: -- Present available steps as numbered options +- Present available workflows and standalone skills as options - Let user select the starting point ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/.claude/skills/update/SKILL.md b/.claude/skills/update/SKILL.md index e4cbc26d..e63bd476 100644 --- a/.claude/skills/update/SKILL.md +++ b/.claude/skills/update/SKILL.md @@ -5,7 +5,7 @@ description: "Updates DeepWork standard jobs in src/ and syncs to installed loca # update -**Multi-step workflow**: Updates DeepWork standard jobs in src/ and syncs to installed locations. Use when modifying deepwork_jobs or deepwork_rules. +Updates DeepWork standard jobs in src/ and syncs to installed locations. Use when modifying deepwork_jobs or deepwork_rules. > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. @@ -24,16 +24,20 @@ Use this job whenever you need to modify job.yml files, step instructions, or ho for any standard job in the DeepWork repository. -## Available Steps +## Standalone Skills + +These skills can be run independently at any time: + +- **job** - Edits standard job source files in src/ and runs deepwork install to sync changes. Use when updating job.yml or step instructions. + Command: `/update.job` -1. **job** - Edits standard job source files in src/ and runs deepwork install to sync changes. Use when updating job.yml or step instructions. ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/update` to determine user intent: -- "job" or related terms → start at `update.job` +- "job" or related terms → run standalone skill `update.job` ### Step 2: Invoke Starting Step @@ -45,10 +49,12 @@ Skill tool: update.job ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: @@ -58,7 +64,7 @@ If user intent is unclear, use AskUserQuestion to clarify: ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/.deepwork/jobs/add_platform/job.yml b/.deepwork/jobs/add_platform/job.yml index ead4b005..80b333dc 100644 --- a/.deepwork/jobs/add_platform/job.yml +++ b/.deepwork/jobs/add_platform/job.yml @@ -1,11 +1,11 @@ name: add_platform -version: "0.3.0" +version: "0.4.0" summary: "Adds a new AI platform to DeepWork with adapter, templates, and tests. Use when integrating Cursor, Windsurf, or other AI coding tools." description: | A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. - This job guides you through four phases: + The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates @@ -20,7 +20,18 @@ description: | - Tests must achieve 100% coverage for any new functionality - Installation verification confirms the platform integrates correctly with existing jobs +workflows: + - name: integrate + summary: "Full workflow to integrate a new AI platform into DeepWork" + steps: + - research + - add_capabilities + - implement + - verify + changelog: + - version: "0.4.0" + changes: "Added workflows section to explicitly define the integrate workflow sequence" - version: "0.1.0" changes: "Initial version" - version: "0.2.0" diff --git a/.deepwork/jobs/commit/job.yml b/.deepwork/jobs/commit/job.yml index 445640df..6760c275 100644 --- a/.deepwork/jobs/commit/job.yml +++ b/.deepwork/jobs/commit/job.yml @@ -1,10 +1,10 @@ name: commit -version: "1.4.0" +version: "1.5.0" summary: "Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks." description: | A workflow for preparing and committing code changes with quality checks. - This job starts with a code review to catch issues early, runs tests until + The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. @@ -15,7 +15,18 @@ description: | 3. lint - Format and lint code with ruff (runs in sub-agent) 4. commit_and_push - Review changes and commit/push +workflows: + - name: full + summary: "Full commit workflow: review, test, lint, and commit" + steps: + - review + - test + - lint + - commit_and_push + changelog: + - version: "1.5.0" + changes: "Added workflows section to explicitly define the full commit workflow sequence" - version: "1.4.0" changes: "Added changelog guidance: entries must go in [Unreleased] section, NEVER modify version numbers in pyproject.toml or CHANGELOG.md" - version: "1.3.0" diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 715fc65a..1cb38621 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,19 +1,29 @@ name: deepwork_jobs -version: "0.9.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 workflows and learn from running them. - The `define` command guides you through an interactive process to create a new job by + The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, - and generating all necessary files. + reviewing the specification, and generating all necessary files. - The `learn` command reflects on conversations where DeepWork jobs were run, identifies + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. +workflows: + - name: new_job + summary: "Create a new DeepWork job from scratch through definition, review, and implementation" + steps: + - define + - review_job_spec + - implement + changelog: + - 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" diff --git a/.deepwork/jobs/manual_tests/job.yml b/.deepwork/jobs/manual_tests/job.yml index 1751a96d..c13ffac3 100644 --- a/.deepwork/jobs/manual_tests/job.yml +++ b/.deepwork/jobs/manual_tests/job.yml @@ -1,10 +1,10 @@ name: manual_tests -version: "1.3.0" +version: "1.4.0" summary: "Runs all manual hook/rule tests using sub-agents. Use when validating that DeepWork rules fire correctly." description: | A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. - This job tests that rules fire when they should AND do not fire when they shouldn't. + The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes @@ -38,7 +38,18 @@ description: | - Infinite block (prompt and command) - in dedicated step - Created mode (new files only) +workflows: + - name: run_all + summary: "Run all manual tests: reset, NOT-fire tests, fire tests, and infinite block tests" + steps: + - reset + - run_not_fire_tests + - run_fire_tests + - infinite_block_tests + changelog: + - version: "1.4.0" + changes: "Added workflows section to explicitly define the run_all test workflow sequence" - version: "1.3.0" changes: "Add model/max_turns config for sub-agents; move infinite block tests to dedicated serial step; add reset step that runs first; verify queue empty for 'should NOT fire' tests" - version: "1.2.1" diff --git a/.gemini/skills/add_platform/add_capabilities.toml b/.gemini/skills/add_platform/add_capabilities.toml index 1860b3ea..8c23d8f0 100644 --- a/.gemini/skills/add_platform/add_capabilities.toml +++ b/.gemini/skills/add_platform/add_capabilities.toml @@ -163,7 +163,7 @@ When you find a new hook type, consider whether it maps to an existing pattern o A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates diff --git a/.gemini/skills/add_platform/implement.toml b/.gemini/skills/add_platform/implement.toml index a6462592..dda3f96e 100644 --- a/.gemini/skills/add_platform/implement.toml +++ b/.gemini/skills/add_platform/implement.toml @@ -255,7 +255,7 @@ The templates use Jinja2 and should produce files that match exactly what the pl A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates diff --git a/.gemini/skills/add_platform/index.toml b/.gemini/skills/add_platform/index.toml index 878f6600..f97f6792 100644 --- a/.gemini/skills/add_platform/index.toml +++ b/.gemini/skills/add_platform/index.toml @@ -15,7 +15,7 @@ prompt = """ A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates diff --git a/.gemini/skills/add_platform/research.toml b/.gemini/skills/add_platform/research.toml index 0c2cd5ae..9e0175c5 100644 --- a/.gemini/skills/add_platform/research.toml +++ b/.gemini/skills/add_platform/research.toml @@ -212,7 +212,7 @@ Take time to be thorough - incomplete documentation will slow down subsequent st A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates diff --git a/.gemini/skills/add_platform/verify.toml b/.gemini/skills/add_platform/verify.toml index 368c6dc7..ab440f09 100644 --- a/.gemini/skills/add_platform/verify.toml +++ b/.gemini/skills/add_platform/verify.toml @@ -139,7 +139,7 @@ Take time to verify each aspect - finding issues now is much better than having A workflow for adding support for a new AI platform (like Cursor, Windsurf, etc.) to DeepWork. -This job guides you through four phases: +The **integrate** workflow guides you through four phases: 1. **Research**: Capture the platform's CLI configuration and hooks system documentation 2. **Add Capabilities**: Update the job schema and adapters with any new hook events 3. **Implement**: Create the platform adapter, templates, tests (100% coverage), and README updates diff --git a/.gemini/skills/commit/commit_and_push.toml b/.gemini/skills/commit/commit_and_push.toml index 251b9a3a..51817636 100644 --- a/.gemini/skills/commit/commit_and_push.toml +++ b/.gemini/skills/commit/commit_and_push.toml @@ -120,7 +120,7 @@ This is the final step of the commit workflow. The agent verifies that the chang A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. diff --git a/.gemini/skills/commit/index.toml b/.gemini/skills/commit/index.toml index 7f7a3986..09eff3ef 100644 --- a/.gemini/skills/commit/index.toml +++ b/.gemini/skills/commit/index.toml @@ -15,7 +15,7 @@ prompt = """ A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. diff --git a/.gemini/skills/commit/lint.toml b/.gemini/skills/commit/lint.toml index f1e037c1..0def799d 100644 --- a/.gemini/skills/commit/lint.toml +++ b/.gemini/skills/commit/lint.toml @@ -100,7 +100,7 @@ This step ensures code quality and consistency before committing. It runs after A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. diff --git a/.gemini/skills/commit/review.toml b/.gemini/skills/commit/review.toml index 40425163..0b9d01fa 100644 --- a/.gemini/skills/commit/review.toml +++ b/.gemini/skills/commit/review.toml @@ -129,7 +129,7 @@ This is the first step of the commit workflow. Code review happens before tests A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. diff --git a/.gemini/skills/commit/test.toml b/.gemini/skills/commit/test.toml index 8c618298..e037884f 100644 --- a/.gemini/skills/commit/test.toml +++ b/.gemini/skills/commit/test.toml @@ -81,7 +81,7 @@ This step runs after code review. Tests must pass before proceeding to lint and A workflow for preparing and committing code changes with quality checks. -This job starts with a code review to catch issues early, runs tests until +The **full** workflow starts with a code review to catch issues early, runs tests until they pass, formats and lints code with ruff, then reviews changed files before committing and pushing. The review and lint steps use sub-agents to reduce context usage. diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 61dec612..745062f3 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -422,11 +422,11 @@ After creating the file: Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml index f0059d3e..582751ef 100644 --- a/.gemini/skills/deepwork_jobs/implement.toml +++ b/.gemini/skills/deepwork_jobs/implement.toml @@ -267,11 +267,11 @@ Before marking this step complete, ensure: Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -312,7 +312,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 1. Verify outputs are created 2. Inform user: "Step 3/4 complete, outputs: steps/" -3. **Tell user next command**: `/deepwork_jobs:learn` +3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. --- diff --git a/.gemini/skills/deepwork_jobs/index.toml b/.gemini/skills/deepwork_jobs/index.toml index b609025d..6756ea88 100644 --- a/.gemini/skills/deepwork_jobs/index.toml +++ b/.gemini/skills/deepwork_jobs/index.toml @@ -16,11 +16,11 @@ prompt = """ Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index 8f093881..e4d7d9a9 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -382,11 +382,11 @@ Updated job instructions and created AGENTS.md with bespoke learnings. To get th Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index b9bed849..4e321d57 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -237,11 +237,11 @@ The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes Core commands for managing DeepWork jobs. These commands help you define new multi-step workflows and learn from running them. -The `define` command guides you through an interactive process to create a new job by +The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, -and generating all necessary files. +reviewing the specification, and generating all necessary files. -The `learn` command reflects on conversations where DeepWork jobs were run, identifies +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.gemini/skills/manual_tests/index.toml b/.gemini/skills/manual_tests/index.toml index 775a7fab..a7f18b16 100644 --- a/.gemini/skills/manual_tests/index.toml +++ b/.gemini/skills/manual_tests/index.toml @@ -15,7 +15,7 @@ prompt = """ A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes diff --git a/.gemini/skills/manual_tests/infinite_block_tests.toml b/.gemini/skills/manual_tests/infinite_block_tests.toml index 929a2601..a1fbf553 100644 --- a/.gemini/skills/manual_tests/infinite_block_tests.toml +++ b/.gemini/skills/manual_tests/infinite_block_tests.toml @@ -164,7 +164,7 @@ This step runs after both the "should NOT fire" and "should fire" test steps. It A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes diff --git a/.gemini/skills/manual_tests/reset.toml b/.gemini/skills/manual_tests/reset.toml index 692c9f20..8d7935f0 100644 --- a/.gemini/skills/manual_tests/reset.toml +++ b/.gemini/skills/manual_tests/reset.toml @@ -62,7 +62,7 @@ deepwork rules clear_queue A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes diff --git a/.gemini/skills/manual_tests/run_fire_tests.toml b/.gemini/skills/manual_tests/run_fire_tests.toml index a8ebbc99..1f471b83 100644 --- a/.gemini/skills/manual_tests/run_fire_tests.toml +++ b/.gemini/skills/manual_tests/run_fire_tests.toml @@ -160,7 +160,7 @@ This step runs after the "should NOT fire" tests. These tests verify that rules A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes diff --git a/.gemini/skills/manual_tests/run_not_fire_tests.toml b/.gemini/skills/manual_tests/run_not_fire_tests.toml index b23d2fa1..2e429635 100644 --- a/.gemini/skills/manual_tests/run_not_fire_tests.toml +++ b/.gemini/skills/manual_tests/run_not_fire_tests.toml @@ -146,7 +146,7 @@ This step runs after the reset step (which ensures a clean environment) and test A workflow for running manual tests that validate DeepWork rules/hooks fire correctly. -This job tests that rules fire when they should AND do not fire when they shouldn't. +The **run_all** workflow tests that rules fire when they should AND do not fire when they shouldn't. Each test is run in a SUB-AGENT (not the main agent) because: 1. Sub-agents run in isolated contexts where file changes can be detected 2. The Stop hook automatically evaluates rules when each sub-agent completes diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e812ebb..7a7be204 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- Explicit workflow definitions in job.yml for distinguishing multi-step workflows from standalone skills + - New `workflows` section in job.yml with `name`, `summary`, and ordered `steps` array + - Workflows are shown separately from standalone skills in generated meta-skills + - Step skills now display workflow context (e.g., "Step 2/3 in new_job workflow") + - Standalone skills are clearly marked as "can be run anytime" + - Backward compatible: jobs without `workflows` section use dependency-based detection ### Changed +- Skill templates now show workflow-aware progress (e.g., "new_job step 2/3 complete") +- Meta-skill template reorganized to show "Workflows" and "Standalone Skills" sections separately +- Updated `deepwork_jobs` standard job to v1.0.0 with explicit `new_job` workflow - SessionStart hook now skips non-initial sessions (resume, compact/clear) by checking the `source` field in stdin JSON, reducing noise and redundant checks ### Fixed diff --git a/doc/architecture.md b/doc/architecture.md index 87532d09..cafd92c3 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -364,6 +364,18 @@ changelog: - version: "1.0.0" changes: "Initial job creation" +# Workflows define named sequences of steps that form complete processes. +# Steps not in any workflow are "standalone skills" that can be run anytime. +workflows: + - name: full_analysis + summary: "Complete competitive analysis from identification through positioning" + steps: + - identify_competitors + - primary_research + - secondary_research + - comparative_report + - positioning + steps: - id: identify_competitors name: "Identify Competitors" @@ -569,15 +581,21 @@ This section describes how AI agents (like Claude Code) actually execute jobs us [Interactive dialog to define all the steps] Claude: ✓ Job 'competitive_research' created with 5 steps - Run /deepwork_jobs.implement to generate skill files - Then run 'deepwork sync' to install skills + new_job step 1/3 complete, outputs: job.yml + Continuing workflow: invoking review_job_spec... - User: /deepwork_jobs.implement + [Claude automatically continues with review_job_spec step] + + Claude: ✓ Job spec validated against quality criteria + new_job step 2/3 complete + Continuing workflow: invoking implement... + + [Claude automatically continues with implement step] Claude: [Generates step instruction files] [Runs deepwork sync] ✓ Skills installed to .claude/skills/ - Run /competitive_research.identify_competitors to start + new_job workflow complete. Run /competitive_research.identify_competitors to start ``` 3. **Execute a Job Instance** (each time you need to do the work): @@ -752,13 +770,16 @@ When all steps are done, remind the user they should: ### Standard Job: `deepwork_jobs` -DeepWork includes a built-in job called `deepwork_jobs` with three commands for managing jobs: +DeepWork includes a built-in job called `deepwork_jobs` for managing jobs. It provides: -1. **`/deepwork_jobs.define`** - Interactive job definition wizard -2. **`/deepwork_jobs.implement`** - Generates step instruction files from job.yml -3. **`/deepwork_jobs.refine`** - Modifies existing job definitions +**Workflows** (multi-step sequences): +- **`new_job`** workflow: `define` → `review_job_spec` → `implement` + - Creates complete job definitions through interactive Q&A, validation, and file generation -These commands are installed automatically when you run `deepwork install`. +**Standalone Skills** (can be run anytime): +- **`/deepwork_jobs.learn`** - Analyzes conversations to improve job instructions and capture learnings + +These skills are installed automatically when you run `deepwork install`. ### The `/deepwork_jobs.define` Command @@ -842,36 +863,32 @@ Claude: Reading job definition from .deepwork/jobs/competitive_research/job.yml. - /competitive_research.positioning ``` -### The `/deepwork_jobs.refine` Command +### The `/deepwork_jobs.learn` Command -Allows updating existing job definitions: +Analyzes conversation history to improve job instructions and capture learnings: ``` -User: /deepwork_jobs.refine +User: /deepwork_jobs.learn -Claude: Which job would you like to refine? - Available jobs: - - competitive_research - - deepwork_jobs +Claude: I'll analyze this conversation for DeepWork job executions... + Found: competitive_research job was executed -User: competitive_research + Identified issues: + 1. Step 2 instructions unclear about source prioritization + 2. Output format for competitor_profiles/ not specified -Claude: Loading competitive_research job definition... - What would you like to update? - 1. Add a new step - 2. Modify existing step - 3. Remove a step - 4. Update metadata + Improvements made: + ✓ Updated steps/primary_research.md with source prioritization guidance + ✓ Added output format example to steps/primary_research.md -User: Add a new step between primary_research and secondary_research + Bespoke learnings captured: + ✓ Created AGENTS.md with project-specific notes about this competitive research instance -Claude: [Interactive dialog...] - ✓ Added step 'social_media_analysis' - ✓ Updated dependencies in job.yml - ✓ Updated changelog with version 1.1.0 - ✓ Please run /deepwork_jobs.implement to generate the new step file + Run 'deepwork sync' to update skills with improved instructions. ``` +This standalone skill can be run anytime after executing a job to capture learnings and improve instructions. + ### Template System Templates are Markdown files with variable interpolation: diff --git a/src/deepwork/core/generator.py b/src/deepwork/core/generator.py index 55028311..859b7070 100644 --- a/src/deepwork/core/generator.py +++ b/src/deepwork/core/generator.py @@ -95,9 +95,12 @@ def _get_jinja_env(self, adapter: AgentAdapter) -> Environment: def _is_standalone_step(self, job: JobDefinition, step: Step) -> bool: """ - Check if a step is standalone (disconnected from the main workflow). + Check if a step is standalone (not part of any workflow). - A standalone step has no dependencies AND no other steps depend on it. + A step is standalone if: + - It's not listed in any workflow definition + - OR (for backward compatibility) no workflows are defined and the step + has no dependencies and no other steps depend on it Args: job: Job definition @@ -106,17 +109,47 @@ def _is_standalone_step(self, job: JobDefinition, step: Step) -> bool: Returns: True if step is standalone """ - # Step has dependencies - not standalone - if step.dependencies: - return False - - # Check if any other step depends on this step - for other_step in job.steps: - if step.id in other_step.dependencies: + # If workflows are defined, use workflow membership + if job.workflows: + return job.get_workflow_for_step(step.id) is None + else: + # Backward compatibility: if no workflows defined, use dependency analysis + # Step has dependencies - not standalone + if step.dependencies: return False + # Check if any other step depends on this step + for other_step in job.steps: + if step.id in other_step.dependencies: + return False + return True + def _get_workflow_context(self, job: JobDefinition, step: Step) -> dict[str, Any]: + """ + Build workflow context for a step. + + Args: + job: Job definition + step: Step to build context for + + Returns: + Workflow context dictionary with workflow info, or empty dict if standalone + """ + workflow = job.get_workflow_for_step(step.id) + if not workflow: + return {} + + position = job.get_step_position_in_workflow(step.id) + return { + "workflow_name": workflow.name, + "workflow_summary": workflow.summary, + "workflow_step_number": position[0] if position else 1, + "workflow_total_steps": position[1] if position else 1, + "workflow_next_step": job.get_next_step_in_workflow(step.id), + "workflow_prev_step": job.get_prev_step_in_workflow(step.id), + } + def _build_hook_context(self, job: JobDefinition, hook_action: Any) -> dict[str, Any]: """ Build context for a single hook action. @@ -188,14 +221,23 @@ def _build_step_context( # Check if this is a standalone step is_standalone = self._is_standalone_step(job, step) - # Determine next and previous steps (only for non-standalone steps) + # Get workflow context (empty dict if standalone) + workflow_ctx = self._get_workflow_context(job, step) + + # Determine next and previous steps based on workflow (if defined) or order next_step = None prev_step = None if not is_standalone: - if step_index < len(job.steps) - 1: - next_step = job.steps[step_index + 1].id - if step_index > 0: - prev_step = job.steps[step_index - 1].id + if workflow_ctx: + # Use workflow-defined order + next_step = workflow_ctx.get("workflow_next_step") + prev_step = workflow_ctx.get("workflow_prev_step") + else: + # Backward compatibility: use step array order + if step_index < len(job.steps) - 1: + next_step = job.steps[step_index + 1].id + if step_index > 0: + prev_step = job.steps[step_index - 1].id # Build hooks context for all lifecycle events # Structure: {platform_event_name: [hook_contexts]} @@ -247,7 +289,7 @@ def _build_step_context( } outputs_context.append(output_ctx) - return { + context = { "job_name": job.name, "job_version": job.version, "job_summary": job.summary, @@ -271,6 +313,11 @@ def _build_step_context( "quality_criteria": step.quality_criteria, # Declarative criteria with framing } + # Add workflow context if step is part of a workflow + context.update(workflow_ctx) + + return context + def _build_meta_skill_context( self, job: JobDefinition, adapter: AgentAdapter ) -> dict[str, Any]: @@ -300,17 +347,37 @@ def _build_meta_skill_context( # job_name.step_id/SKILL.md -> job_name.step_id skill_name = skill_filename.replace("/SKILL.md", "") - steps_info.append( + # Get workflow info for step + workflow = job.get_workflow_for_step(step.id) + step_info = { + "id": step.id, + "name": step.name, + "description": step.description, + "command_name": skill_name, + "dependencies": step.dependencies, + "exposed": step.exposed, + "is_standalone": self._is_standalone_step(job, step), + } + if workflow: + step_info["workflow_name"] = workflow.name + + steps_info.append(step_info) + + # Build workflow info + workflows_info = [] + for workflow in job.workflows: + workflows_info.append( { - "id": step.id, - "name": step.name, - "description": step.description, - "command_name": skill_name, - "dependencies": step.dependencies, - "exposed": step.exposed, + "name": workflow.name, + "summary": workflow.summary, + "steps": workflow.steps, + "first_step": workflow.steps[0] if workflow.steps else None, } ) + # Identify standalone steps (not in any workflow) + standalone_steps = [s for s in steps_info if s["is_standalone"]] + return { "job_name": job.name, "job_version": job.version, @@ -318,6 +385,9 @@ def _build_meta_skill_context( "job_description": job.description, "total_steps": len(job.steps), "steps": steps_info, + "workflows": workflows_info, + "standalone_steps": standalone_steps, + "has_workflows": bool(job.workflows), } def generate_meta_skill( diff --git a/src/deepwork/core/parser.py b/src/deepwork/core/parser.py index b4ae40ab..7541d49e 100644 --- a/src/deepwork/core/parser.py +++ b/src/deepwork/core/parser.py @@ -183,6 +183,24 @@ def from_dict(cls, data: dict[str, Any]) -> "Step": ) +@dataclass +class Workflow: + """Represents a named workflow grouping steps into a multi-step sequence.""" + + name: str + summary: str + steps: list[str] # List of step IDs in order + + @classmethod + def from_dict(cls, data: dict[str, Any]) -> "Workflow": + """Create Workflow from dictionary.""" + return cls( + name=data["name"], + summary=data["summary"], + steps=data["steps"], + ) + + @dataclass class JobDefinition: """Represents a complete job definition.""" @@ -193,6 +211,7 @@ class JobDefinition: description: str | None steps: list[Step] job_dir: Path + workflows: list[Workflow] = field(default_factory=list) def get_step(self, step_id: str) -> Step | None: """ @@ -308,6 +327,114 @@ def get_doc_spec_references(self) -> list[str]: doc_spec_refs.add(output.doc_spec) return list(doc_spec_refs) + def get_workflow_for_step(self, step_id: str) -> Workflow | None: + """ + Get the workflow containing a step. + + Args: + step_id: Step ID to look up + + Returns: + Workflow containing the step, or None if step is standalone + """ + for workflow in self.workflows: + if step_id in workflow.steps: + return workflow + return None + + def get_next_step_in_workflow(self, step_id: str) -> str | None: + """ + Get the next step in a workflow after the given step. + + Args: + step_id: Current step ID + + Returns: + Next step ID, or None if this is the last step or not in a workflow + """ + workflow = self.get_workflow_for_step(step_id) + if not workflow: + return None + try: + index = workflow.steps.index(step_id) + if index < len(workflow.steps) - 1: + return workflow.steps[index + 1] + except ValueError: + pass + return None + + def get_prev_step_in_workflow(self, step_id: str) -> str | None: + """ + Get the previous step in a workflow before the given step. + + Args: + step_id: Current step ID + + Returns: + Previous step ID, or None if this is the first step or not in a workflow + """ + workflow = self.get_workflow_for_step(step_id) + if not workflow: + return None + try: + index = workflow.steps.index(step_id) + if index > 0: + return workflow.steps[index - 1] + except ValueError: + pass + return None + + def get_step_position_in_workflow(self, step_id: str) -> tuple[int, int] | None: + """ + Get the position of a step within its workflow. + + Args: + step_id: Step ID to look up + + Returns: + Tuple of (1-based position, total steps in workflow), or None if standalone + """ + workflow = self.get_workflow_for_step(step_id) + if not workflow: + return None + try: + index = workflow.steps.index(step_id) + return (index + 1, len(workflow.steps)) + except ValueError: + return None + + def validate_workflows(self) -> None: + """ + Validate workflow definitions. + + Raises: + ParseError: If workflow references non-existent steps or has duplicates + """ + step_ids = {step.id for step in self.steps} + workflow_names = set() + + for workflow in self.workflows: + # Check for duplicate workflow names + if workflow.name in workflow_names: + raise ParseError(f"Duplicate workflow name: '{workflow.name}'") + workflow_names.add(workflow.name) + + # Check all step references exist + for step_id in workflow.steps: + if step_id not in step_ids: + raise ParseError( + f"Workflow '{workflow.name}' references non-existent step '{step_id}'" + ) + + # Check for duplicate steps within a workflow + seen_steps = set() + for step_id in workflow.steps: + if step_id in seen_steps: + raise ParseError( + f"Workflow '{workflow.name}' contains duplicate step '{step_id}'" + ) + seen_steps.add(step_id) + @classmethod def from_dict(cls, data: dict[str, Any], job_dir: Path) -> "JobDefinition": """ @@ -320,6 +447,7 @@ def from_dict(cls, data: dict[str, Any], job_dir: Path) -> "JobDefinition": Returns: JobDefinition instance """ + workflows = [Workflow.from_dict(wf_data) for wf_data in data.get("workflows", [])] return cls( name=data["name"], version=data["version"], @@ -327,6 +455,7 @@ def from_dict(cls, data: dict[str, Any], job_dir: Path) -> "JobDefinition": description=data.get("description"), steps=[Step.from_dict(step_data) for step_data in data["steps"]], job_dir=job_dir, + workflows=workflows, ) @@ -373,8 +502,9 @@ def parse_job_definition(job_dir: Path | str) -> JobDefinition: # Parse into dataclass job_def = JobDefinition.from_dict(job_data, job_dir_path) - # Validate dependencies and file inputs + # Validate dependencies, file inputs, and workflows job_def.validate_dependencies() job_def.validate_file_inputs() + job_def.validate_workflows() return job_def diff --git a/src/deepwork/schemas/job_schema.py b/src/deepwork/schemas/job_schema.py index 03bb598a..0a0622a3 100644 --- a/src/deepwork/schemas/job_schema.py +++ b/src/deepwork/schemas/job_schema.py @@ -46,6 +46,35 @@ ], } +# Schema for a workflow definition +WORKFLOW_SCHEMA: dict[str, Any] = { + "type": "object", + "required": ["name", "summary", "steps"], + "properties": { + "name": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*$", + "description": "Workflow name (lowercase letters, numbers, underscores)", + }, + "summary": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "description": "Brief one-line summary of what this workflow accomplishes", + }, + "steps": { + "type": "array", + "minItems": 1, + "description": "Ordered list of step IDs that comprise this workflow", + "items": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*$", + }, + }, + }, + "additionalProperties": False, +} + # JSON Schema for job.yml files JOB_SCHEMA: dict[str, Any] = { "$schema": "http://json-schema.org/draft-07/schema#", @@ -73,6 +102,11 @@ "minLength": 1, "description": "Detailed multi-line description of the job's purpose, process, and goals", }, + "workflows": { + "type": "array", + "description": "Named workflows that group steps into multi-step sequences", + "items": WORKFLOW_SCHEMA, + }, "changelog": { "type": "array", "description": "Version history and changes to the job", diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 715fc65a..1cb38621 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,19 +1,29 @@ name: deepwork_jobs -version: "0.9.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 workflows and learn from running them. - The `define` command guides you through an interactive process to create a new job by + The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, - and generating all necessary files. + reviewing the specification, and generating all necessary files. - The `learn` command reflects on conversations where DeepWork jobs were run, identifies + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. +workflows: + - name: new_job + summary: "Create a new DeepWork job from scratch through definition, review, and implementation" + steps: + - define + - review_job_spec + - implement + changelog: + - 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" diff --git a/src/deepwork/templates/claude/skill-job-meta.md.jinja b/src/deepwork/templates/claude/skill-job-meta.md.jinja index a45e9345..1bedb8a2 100644 --- a/src/deepwork/templates/claude/skill-job-meta.md.jinja +++ b/src/deepwork/templates/claude/skill-job-meta.md.jinja @@ -7,12 +7,21 @@ Template Variables: - job_summary: string - Short one-line summary of the job - job_description: string|null - Full description (optional) - total_steps: int - Number of steps in the job + - has_workflows: bool - True if workflows are defined + - workflows: list - Array of workflow objects: + - name: string - Workflow identifier + - summary: string - Short description of workflow + - steps: list[string] - Ordered list of step IDs + - first_step: string - First step ID to start workflow + - standalone_steps: list - Steps not in any workflow (same structure as steps) - steps: list - Array of step objects: - id: string - Step identifier - name: string - Human-readable step name - description: string - What the step does - command_name: string - Slash command (e.g., "job_name.step_id") - dependencies: list[string]|null - Required prior steps + - is_standalone: bool - True if not in any workflow + - workflow_name: string|null - Name of workflow if in one #} --- name: {{ job_name }} @@ -21,7 +30,7 @@ description: "{{ job_summary }}" # {{ job_name }} -**Multi-step workflow**: {{ job_summary }} +{{ job_summary }} > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. @@ -29,46 +38,99 @@ description: "{{ job_summary }}" {{ job_description }} {% endif %} +{% if has_workflows %} +## Workflows + +{% for workflow in workflows %} +### {{ workflow.name }} + +{{ workflow.summary }} + +**Steps in order**: +{% for step_id in workflow.steps %} +{% set step = steps | selectattr("id", "equalto", step_id) | first %} +{{ loop.index }}. **{{ step_id }}** - {{ step.description if step else "Unknown step" }} +{% endfor %} + +**Start workflow**: `/{{ job_name }}.{{ workflow.first_step }}` + +{% endfor %} +{% endif %} +{% if standalone_steps %} +## Standalone Skills + +These skills can be run independently at any time: + +{% for step in standalone_steps %} +- **{{ step.id }}** - {{ step.description }} + Command: `/{{ step.command_name }}` +{% endfor %} + +{% endif %} +{% if not has_workflows and not standalone_steps %} ## Available Steps {% for step in steps %} {{ loop.index }}. **{{ step.id }}** - {{ step.description }}{% if step.dependencies %} (requires: {{ step.dependencies | join(', ') }}){% endif %} {% endfor %} +{% endif %} ## Execution Instructions ### Step 1: Analyze Intent Parse any text following `/{{ job_name }}` to determine user intent: +{% if has_workflows %} +{% for workflow in workflows %} +- "{{ workflow.name }}" or related terms → start {{ workflow.name }} workflow at `{{ job_name }}.{{ workflow.first_step }}` +{% endfor %} +{% endif %} +{% for step in standalone_steps %} +- "{{ step.id }}" or related terms → run standalone skill `{{ step.command_name }}` +{% endfor %} +{% if not has_workflows and not standalone_steps %} {% for step in steps %} - "{{ step.id }}" or related terms → start at `{{ step.command_name }}` {% endfor %} +{% endif %} ### Step 2: Invoke Starting Step Use the Skill tool to invoke the identified starting step: +{% if has_workflows and workflows %} +``` +Skill tool: {{ job_name }}.{{ workflows[0].first_step }} +``` +{% else %} ``` Skill tool: {{ steps[0].command_name }} ``` +{% endif %} ### Step 3: Continue Workflow Automatically After each step completes: -1. Check if there's a next step in the sequence +1. Check if there's a next step in the workflow sequence 2. Invoke the next step using the Skill tool 3. Repeat until workflow is complete or user intervenes +**Note**: Standalone skills do not auto-continue to other steps. + ### Handling Ambiguous Intent If user intent is unclear, use AskUserQuestion to clarify: +{% if has_workflows %} +- Present available workflows and standalone skills as options +{% else %} - Present available steps as numbered options +{% endif %} - Let user select the starting point ## Guardrails - Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps -- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT skip steps in a workflow unless the user explicitly requests it - Do NOT proceed to the next step if the current step's outputs are incomplete - Do NOT make assumptions about user intent; ask for clarification when ambiguous diff --git a/src/deepwork/templates/claude/skill-job-step.md.jinja b/src/deepwork/templates/claude/skill-job-step.md.jinja index 610f6cd8..ebb494b2 100644 --- a/src/deepwork/templates/claude/skill-job-step.md.jinja +++ b/src/deepwork/templates/claude/skill-job-step.md.jinja @@ -11,14 +11,22 @@ Template Variables: Step Metadata: - step_id: string - Step identifier - step_description: string - What this step does - - step_number: int - Position in workflow (1-indexed) + - step_number: int - Position in steps array (1-indexed, for backward compat) - total_steps: int - Total steps in job - - is_standalone: bool - True if step can run independently + - is_standalone: bool - True if step can run independently (not in any workflow) - exposed: bool - True if user can invoke directly (default: true) - dependencies: list[string]|null - Required prior step IDs - next_step: string|null - Next step ID in workflow - instructions_file: string - Path to step instructions file + Workflow Context (only if step is in a workflow): + - workflow_name: string - Name of the workflow this step belongs to + - workflow_summary: string - Summary of the workflow + - workflow_step_number: int - Position in workflow (1-indexed) + - workflow_total_steps: int - Total steps in this workflow + - workflow_next_step: string|null - Next step ID in workflow + - workflow_prev_step: string|null - Previous step ID in workflow + Step Content: - instructions_content: string - Full instructions markdown - user_inputs: list|null - User parameters to gather: @@ -91,6 +99,10 @@ hooks: {% if is_standalone %} **Standalone skill** - can be run anytime +{% elif workflow_name %} +**Step {{ workflow_step_number }}/{{ workflow_total_steps }}** in **{{ workflow_name }}** workflow + +> {{ workflow_summary }} {% else %} **Step {{ step_number }}/{{ total_steps }}** in **{{ job_name }}** workflow {% endif %}{#- if is_standalone #} @@ -220,6 +232,14 @@ Use a sub-agent (Haiku model) to review your work against these criteria: 2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}" This standalone skill can be re-run anytime. +{% elif workflow_name %} +1. Verify outputs are created +2. Inform user: "{{ workflow_name }} step {{ workflow_step_number }}/{{ workflow_total_steps }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}" +{% if next_step %} +3. **Continue workflow**: Use Skill tool to invoke `/{{ job_name }}.{{ next_step }}` +{% else %} +3. **{{ workflow_name }} workflow complete**: All steps finished. Consider creating a PR to merge the work branch. +{% endif %}{#- if next_step #} {% else %} 1. Verify outputs are created 2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}" diff --git a/tests/integration/test_install_flow.py b/tests/integration/test_install_flow.py index beabf811..d0638275 100644 --- a/tests/integration/test_install_flow.py +++ b/tests/integration/test_install_flow.py @@ -51,7 +51,8 @@ def test_install_with_claude(self, mock_claude_project: Path) -> None: # Verify meta-skill content meta_skill = (claude_dir / "deepwork_jobs" / "SKILL.md").read_text() assert "# deepwork_jobs" in meta_skill - assert "Available Steps" in meta_skill + # deepwork_jobs has workflows defined, so it shows "Workflows" instead of "Available Steps" + assert "Workflows" in meta_skill or "Available Steps" in meta_skill # Verify step skill content define_skill = (claude_dir / "deepwork_jobs.define" / "SKILL.md").read_text()