-
Notifications
You must be signed in to change notification settings - Fork 3
feat(standard_jobs): add engineer standard job #287
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| job_definition_review: | ||
| description: "Review job.yml, requirements.md, and step instructions for correctness, completeness, and coherence as a holistic workflow." | ||
| match: | ||
| include: | ||
| - "job.yml" | ||
| - "steps/*.md" | ||
| - "requirements.md" | ||
| review: | ||
| strategy: matches_together | ||
| instructions: | | ||
| Review this DeepWork job definition (job.yml), its requirements (requirements.md), | ||
| and its step instruction files (steps/*.md) holistically. Check that they form a | ||
| coherent, well-structured workflow that an AI agent can execute reliably. | ||
|
|
||
| ## Reference Material | ||
|
|
||
| For reference on correct job structure and best practices, read the following files from your plugin: | ||
| - `job.yml.template` — canonical job.yml structure with all supported fields | ||
| - `job.yml.example` — a complete working example (competitive research job) | ||
| - `step_instruction.md.template` — expected structure for step instruction files | ||
| - `research_report_job_best_practices.md` — design patterns for report-type jobs | ||
|
|
||
| ## What to Check | ||
|
|
||
| ### 1. job.yml Structure | ||
| - Has required fields: `name`, `version`, `summary`, `workflows`, `steps` | ||
| - `name` is lowercase with underscores only | ||
| - `summary` is concise (under 200 characters) and descriptive enough to let a user know what the job does | ||
| - `version` follows semantic versioning (e.g., "1.0.0") | ||
| - `common_job_info_provided_to_all_steps_at_runtime` provides useful shared context (problem domain, terminology, conventions, constraints) | ||
|
|
||
| ### 2. Workflow Coherence | ||
| - Each workflow's steps form a logical sequence toward a clear goal | ||
| - Step dependencies are declared correctly (no missing or extraneous deps) | ||
| - No circular dependencies exist | ||
|
|
||
| ### 3. Input/Output Chain | ||
| - Each step has at least one output | ||
| - File inputs reference outputs from steps listed in that step's dependencies | ||
| - `from_step` values match actual step IDs that produce the referenced file | ||
| - The output chain creates a logical data flow through the workflow | ||
| - Intermediate outputs that are not meant to be persisted should be in .deepwork/tmp (and the name should indicate that) | ||
| - Final outputs follow project conventions (not hidden in dot-directories, descriptive names, appropriate use of subdirectories) | ||
|
|
||
| ### 4. Step Instructions Match job.yml | ||
| - Every step defined in job.yml has a corresponding instruction file | ||
| - Step instruction content aligns with the step's described purpose | ||
| - Instructions reference the correct input and output filenames from job.yml | ||
| - Instructions do not duplicate content already in `common_job_info_provided_to_all_steps_at_runtime` | ||
| - If there is duplicated content amongst the instruction files, it should be moved to `common_job_info_provided_to_all_steps_at_runtime` and removed from the instruction files | ||
| - If there is content that is needed in multiple steps but not all, it should be moved to its own file and referenced in the steps | ||
|
|
||
| ### 5. Quality Reviews | ||
| - Steps with complex or final outputs have reviews defined | ||
| - `run_each` values reference valid output names or `step` | ||
| - Quality criteria are statements of expected state, not questions | ||
| - `additional_review_guidance` is used when reviewers need context beyond the step's own output files (e.g., cross-referencing prior step outputs) | ||
| - Steps with no meaningful quality checks use `reviews: []` | ||
|
|
||
| ### 6. Step Instruction Quality | ||
| - Each instruction file follows the structure and section headings defined in | ||
| `step_instruction.md.template` for this job type. | ||
| - The sections clearly communicate: what the step is trying to achieve, | ||
| what the agent should do, what to produce (including format/examples), | ||
| and how quality will be evaluated. | ||
| - Instructions are specific and actionable, not generic placeholders | ||
| - Output format sections show what good output looks like (examples or | ||
| templates) | ||
| - If the step gathers user input, instructions mention using structured | ||
| questions (e.g., the AskUserQuestion tool) | ||
| - Instructions explain how to use file inputs from prior steps and how the | ||
| step's outputs will be consumed by later steps. | ||
|
|
||
| ## Output Format | ||
|
|
||
| - PASS: The job definition and step instructions are coherent and | ||
| well-structured. | ||
| - FAIL: List each issue with the specific file, the problem, and a | ||
| suggested fix. | ||
| additional_context: | ||
| unchanged_matching_files: true |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # Project Context for engineer | ||
|
|
||
| ## Location | ||
|
|
||
| This job lives in the DeepWork package source at `src/deepwork/standard_jobs/engineer/`. | ||
| It is loaded directly at runtime by the multi-folder job discovery system. | ||
|
|
||
| ## File Organization | ||
|
|
||
| ``` | ||
| engineer/ | ||
| ├── AGENTS.md # This file | ||
| ├── CLAUDE.md -> AGENTS.md # Symlink for Claude Code | ||
| ├── job.yml # Job definition | ||
| ├── requirements.md # RFC 2119 requirements specification | ||
| └── steps/ | ||
| ├── translate_issue.md | ||
| ├── initialize_branch.md | ||
| ├── red_tests.md | ||
| ├── green_implementation.md | ||
| ├── finalize_pr.md | ||
| ├── product_sync.md | ||
| ├── check_agent_md.md | ||
| ├── check_context.md | ||
| └── doctor_report.md | ||
| ``` | ||
|
|
||
| ## Workflows | ||
|
|
||
| - **implement**: 6-step workflow executing engineering work from product issue through PR merge and product sync | ||
| - **doctor**: 3-step workflow validating agent.md and domain context files | ||
|
|
||
| ## Design Decisions | ||
|
|
||
| 1. **Domain-agnostic**: Domain adaptation tables (software, hardware, CAD, firmware, docs) live in `job.yml` `common_job_info`; step instructions are written to be domain-agnostic and rely on those tables | ||
| 2. **Six implement steps**: Preserves TDD discipline boundary (red tests committed before green implementation) | ||
| 3. **product_sync is separate**: Workflow can pause at finalize_pr while PR undergoes human review | ||
| 4. **Doctor focuses on agent.md**: Recommends `repo` library job for labels/branch protection/milestones | ||
| 5. **Requirements bundled**: RFC 2119 spec lives alongside job definition as `requirements.md` | ||
|
|
||
| ## Last Updated | ||
| - Date: 2026-03-24 | ||
| - From conversation about: Initial creation of the engineer standard job |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| AGENTS.md |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The “Current standard jobs” list is missing
deepwork_reviews, butsrc/deepwork/standard_jobs/deepwork_reviews/exists (and is documented elsewhere in the repo). Please add it here so the list stays complete.