diff --git a/AGENTS.md b/AGENTS.md index 0fbe57c0..c7d18854 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,8 @@ When creating or modifying jobs in this repository, you MUST understand which ty **Current standard jobs**: - `deepwork_jobs` - Core job management (define, implement, learn) +- `engineer` - Domain-agnostic engineering execution (implement, doctor) +- `deepwork_reviews` - DeepWork job review and quality control workflows **Editing rules**: - Source of truth is ALWAYS in `src/deepwork/standard_jobs/` @@ -104,7 +106,8 @@ deepwork/ │ ├── hooks/ # Hook scripts and wrappers │ ├── standard_jobs/ # Built-in job definitions (auto-discovered at runtime) │ │ ├── deepwork_jobs/ -│ │ └── deepwork_reviews/ +│ │ ├── deepwork_reviews/ +│ │ └── engineer/ │ ├── review/ # DeepWork Reviews system (.deepreview pipeline) │ ├── schemas/ # Definition schemas (deepreview, doc_spec) │ └── utils/ # Utilities (fs, git, yaml, validation) @@ -221,7 +224,7 @@ Each step: ### How to Identify Job Types -- **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_reviews`) +- **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_reviews`, `engineer`) - **Library jobs**: Exist in `library/jobs/` - **Bespoke jobs**: Exist ONLY in `.deepwork/jobs/` with no corresponding standard_jobs entry @@ -242,3 +245,4 @@ Each step: 5. **Type Safety**: Use type hints for better code quality 6. **No Auto-Commit**: DO NOT automatically commit changes to git. Let the user review and commit changes themselves. 7. **Documentation Sync**: When making implementation changes, always update `doc/architecture.md` and `README.md` to reflect those changes. The architecture document must stay in sync with the actual codebase. +8. **Succinctness**: Jobs, documentation, and code MUST be succinct. Avoid verbose preambles, redundant explanations, and duplicated content. Step instructions should contain only what the agent needs to act — not philosophy, not quality criteria already enforced by the workflow runtime, and not domain tables already in `common_job_info`. If it can be said in one sentence, do not use three. diff --git a/doc/architecture.md b/doc/architecture.md index d7c6eae6..3f80be61 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -65,7 +65,8 @@ deepwork/ # DeepWork tool repository │ │ └── gemini_hook.sh # Shell wrapper for Gemini CLI │ ├── standard_jobs/ # Built-in job definitions │ │ ├── deepwork_jobs/ -│ │ └── deepwork_reviews/ +│ │ ├── deepwork_reviews/ +│ │ └── engineer/ │ ├── review/ # DeepWork Reviews system │ │ ├── config.py # .deepreview config parsing + data models │ │ ├── discovery.py # Find .deepreview files in project tree @@ -617,6 +618,18 @@ DeepWork includes a built-in job called `deepwork_reviews` for managing `.deepre - **`add_document_update_rule`** workflow: `analyze_dependencies` → `apply_rule` - Adds a review rule to keep a specific documentation file up-to-date when related source files change +### Standard Job: `engineer` + +DeepWork includes a built-in job called `engineer` for domain-agnostic engineering execution. It provides: + +**Workflows**: +- **`implement`** workflow: `translate_issue` → `initialize_branch` → `red_tests` → `green_implementation` → `finalize_pr` → `product_sync` + - Drives engineering work from product issue through PR merge with TDD discipline, PR synchronization, and product traceability +- **`doctor`** workflow: `check_agent_md` → `check_context` → `doctor_report` + - Validates that agent.md and domain context files are present, linked, and valid + +The job is domain-agnostic — its `common_job_info` includes a domain adaptation table for software, hardware/CAD, firmware, and documentation projects that step instructions reference. An RFC 2119 requirements specification is bundled as `requirements.md`. + ### MCP-Based Workflow Execution Users invoke workflows through the `/deepwork` skill, which uses MCP tools: diff --git a/src/deepwork/standard_jobs/engineer/.deepreview b/src/deepwork/standard_jobs/engineer/.deepreview new file mode 100644 index 00000000..fa22a5f3 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/.deepreview @@ -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 diff --git a/src/deepwork/standard_jobs/engineer/AGENTS.md b/src/deepwork/standard_jobs/engineer/AGENTS.md new file mode 100644 index 00000000..49ad212e --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/AGENTS.md @@ -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 diff --git a/src/deepwork/standard_jobs/engineer/CLAUDE.md b/src/deepwork/standard_jobs/engineer/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/deepwork/standard_jobs/engineer/job.yml b/src/deepwork/standard_jobs/engineer/job.yml new file mode 100644 index 00000000..49450519 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/job.yml @@ -0,0 +1,291 @@ +# yaml-language-server: $schema=.deepwork/schemas/job.schema.json +name: engineer +version: "1.0.0" +summary: "Domain-agnostic engineering execution from product issue through PR merge and product sync, with TDD discipline" +common_job_info_provided_to_all_steps_at_runtime: | + This job drives engineering work from product issue through merged PR and product sync. + It enforces test-driven development, continuous PR synchronization, artifact generation, + and product traceability across any engineering domain (software, hardware, CAD, firmware, + documentation). + + ## Requirements Reference + + This job implements an RFC 2119 requirements specification bundled as `requirements.md` + in the job directory. Step instructions reference requirements by number (Req 1-8). + Read `requirements.md` for the full normative text. + + ## Domain Adaptation + + The workflow is domain-agnostic. This common job info provides a domain adaptation + table mapping generic concepts to domain-specific equivalents that applies across all steps: + + | Concept | Software | Hardware/CAD | Firmware | Docs | + |-----------------|-------------------|--------------------|-------------------|------------------| + | Test | Unit/integration | DRC/simulation | HIL/unit test | Link check/lint | + | Build artifact | Binary/container | STL/STEP/Gerber | .hex/.bin | PDF/HTML | + | CI visual | DOM snapshot | Rendered STL | Logic trace | PDF render | + | Branch | Git branch | Git branch | Git branch | Git branch | + + The agent MUST read the repository's `agent.md` (or equivalent context file) to determine + the project's domain and adapt accordingly. If no `agent.md` exists, the `doctor` workflow + SHOULD be run first. + + ## PR Synchronization + + Throughout the `implement` workflow, PR checkboxes MUST be kept synchronized with the + worktree state. Every time a task is completed and pushed, the corresponding PR checkbox + MUST be updated immediately. + + ## Work Product Storage + + Step outputs are DeepWork tracking files stored in `.deepwork/tmp/`. The actual engineering + artifacts (code, tests, configs, schematics) live in the repository's normal directory + structure as determined by the project's conventions. + +workflows: + - name: implement + summary: "Execute engineering work from product issue through PR merge and product sync" + steps: + - translate_issue + - initialize_branch + - red_tests + - green_implementation + - finalize_pr + - product_sync + + - name: doctor + summary: "Validate that agent.md and domain context files are present, linked, and valid" + steps: + - check_agent_md + - check_context + - doctor_report + +steps: + # ── Implement Workflow ───────────────────────────────────────────── + + - id: translate_issue + name: "Translate Product Issue to Engineering Issue" + description: "Read the product issue, extract requirements, and create a distinct engineering issue with implementation plan, test definitions, and traceability links." + instructions_file: steps/translate_issue.md + inputs: + - name: product_issue + description: "URL or identifier of the product issue containing the user story and requirements" + outputs: + .deepwork/tmp/engineering_issue.md: + type: file + description: "Engineering issue content: implementation plan, test definitions, and requirement traceability" + required: true + .deepwork/tmp/engineering_issue_url.md: + type: file + description: "URL of the created engineering issue on the git platform" + required: true + dependencies: [] + reviews: + - run_each: .deepwork/tmp/engineering_issue.md + quality_criteria: + "Implementation Plan Present": "The engineering issue contains a concrete implementation plan with actionable tasks." + "Test Definitions Present": "The engineering issue defines expected red and green test states for each requirement." + "Requirement Traceability": "Every requirement from the product issue is explicitly referenced and mapped to implementation tasks." + "Distinct From Product Issue": "The engineering issue is a separate artifact from the product issue, not a copy." + + - id: initialize_branch + name: "Initialize Branch and Draft PR" + description: "Create a dedicated git worktree or branch, commit the engineering specification, and open a draft PR using the repository's PR template." + instructions_file: steps/initialize_branch.md + inputs: + - file: .deepwork/tmp/engineering_issue.md + from_step: translate_issue + - file: .deepwork/tmp/engineering_issue_url.md + from_step: translate_issue + outputs: + .deepwork/tmp/branch_context.md: + type: file + description: "Branch name, PR URL, and initial commit SHA" + required: true + dependencies: + - translate_issue + reviews: + - run_each: .deepwork/tmp/branch_context.md + quality_criteria: + "Branch Created": "A dedicated branch or worktree exists for the engineering issue." + "Spec Committed": "The engineering specification was committed before any implementation code." + "Draft PR Opened": "A draft PR was opened using the repository's standardized PR template." + "PR Links Issue": "The PR references the engineering issue URL." + + - id: red_tests + name: "Write Failing Tests" + description: "Implement new failing tests or verify existing tests against new requirements. Each test must reference a specific requirement from the engineering issue." + instructions_file: steps/red_tests.md + inputs: + - file: .deepwork/tmp/engineering_issue.md + from_step: translate_issue + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + outputs: + .deepwork/tmp/test_manifest.md: + type: file + description: "Manifest mapping each test to its requirement, with red state verification" + required: true + dependencies: + - translate_issue + - initialize_branch + reviews: + - run_each: .deepwork/tmp/test_manifest.md + additional_review_guidance: "Read .deepwork/tmp/engineering_issue.md to verify that every requirement has at least one corresponding test." + quality_criteria: + "Requirement Coverage": "Every requirement from the engineering issue has at least one corresponding test." + "Tests Are Red": "All new tests are verified to be in a failing state before implementation begins." + "Requirement References": "Each test explicitly references the specific requirement it validates." + "Tests Committed Separately": "Failing tests were committed separately from any implementation code." + + - id: green_implementation + name: "Implement to Pass Tests" + description: "Implement the necessary logic, parameters, or configuration to transition all tests to a passing state. Keep PR checkboxes synchronized with progress." + instructions_file: steps/green_implementation.md + inputs: + - file: .deepwork/tmp/engineering_issue.md + from_step: translate_issue + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + - file: .deepwork/tmp/test_manifest.md + from_step: red_tests + outputs: + .deepwork/tmp/implementation_summary.md: + type: file + description: "Summary of implementation changes, test results, and PR checkbox state" + required: true + dependencies: + - translate_issue + - initialize_branch + - red_tests + reviews: + - run_each: .deepwork/tmp/implementation_summary.md + additional_review_guidance: "Read .deepwork/tmp/test_manifest.md to verify all tests transitioned from red to green." + quality_criteria: + "All Tests Green": "All tests from the test manifest have transitioned to a passing state." + "PR Checkboxes Synchronized": "PR checkboxes reflect the current state of completed tasks." + "Changes Pushed": "All implementation changes have been pushed to the remote branch." + "No Unrelated Changes": "The implementation contains only changes necessary to satisfy the requirements." + + - id: finalize_pr + name: "Finalize PR with Artifacts" + description: "Ensure CI generates visual artifacts, populate the PR ## Demo section, document handoff notes, and verify all checkboxes are complete." + instructions_file: steps/finalize_pr.md + inputs: + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + - file: .deepwork/tmp/implementation_summary.md + from_step: green_implementation + outputs: + .deepwork/tmp/pr_finalization.md: + type: file + description: "PR finalization status: artifact verification, demo section, handoff notes, checkbox state" + required: true + dependencies: + - initialize_branch + - green_implementation + reviews: + - run_each: .deepwork/tmp/pr_finalization.md + quality_criteria: + "Visual Artifacts Present": "The PR ## Demo section displays automatically generated visual artifacts relevant to the domain." + "Handoff Documented": "If the implementation unblocks downstream work, handoff notes are documented in the PR." + "Checkboxes Complete": "All PR task checkboxes are checked and synchronized with the branch state." + "PR Undrafted": "The PR has been undrafted (transitioned to ready for review) and code owner reviewers have been requested." + + - id: product_sync + name: "Synchronize Product Issue" + description: "After PR merge, author a formal comment on the parent product issue with completed user stories and immutable links to the merged PR and closed engineering issue." + instructions_file: steps/product_sync.md + inputs: + - file: .deepwork/tmp/engineering_issue_url.md + from_step: translate_issue + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + - file: .deepwork/tmp/pr_finalization.md + from_step: finalize_pr + outputs: + .deepwork/tmp/product_sync_record.md: + type: file + description: "Record of the product issue comment: content posted, links included, timestamp" + required: true + dependencies: + - translate_issue + - initialize_branch + - finalize_pr + reviews: + - run_each: .deepwork/tmp/product_sync_record.md + quality_criteria: + "Comment Posted": "A formal comment was authored on the parent product issue." + "User Stories Documented": "The comment documents which high-level user stories were completed." + "Immutable Links": "The comment contains immutable links to the merged PR and closed engineering issue." + "Product Manager Visibility": "The comment provides enough context for product managers to understand progress without parsing engineering telemetry." + + # ── Doctor Workflow ──────────────────────────────────────────────── + + - id: check_agent_md + name: "Check Agent Context File" + description: "Verify that agent.md (or equivalent) exists, defines the engineering domain, and contains build/test/parse instructions for automated agents." + instructions_file: steps/check_agent_md.md + inputs: + - name: project_path + description: "Path to the repository root to check (defaults to current directory if omitted)" + outputs: + .deepwork/tmp/agent_md_audit.md: + type: file + description: "Audit results for agent.md: existence, domain declaration, build/test instructions" + required: true + dependencies: [] + reviews: + - run_each: .deepwork/tmp/agent_md_audit.md + quality_criteria: + "File Existence Checked": "The audit verifies whether agent.md (or equivalent) exists at the repository root." + "Domain Declared": "The audit checks whether the file explicitly defines the project's engineering domain." + "Agent Instructions Present": "The audit checks for build, test, and parse instructions that automated agents need." + "CODEOWNERS Present": "The audit checks for a CODEOWNERS file needed for automatic reviewer assignment." + + - id: check_context + name: "Check Supporting Context Files" + description: "Verify that supporting context files referenced by agent.md are present, correctly linked, and syntactically valid." + instructions_file: steps/check_context.md + inputs: + - file: .deepwork/tmp/agent_md_audit.md + from_step: check_agent_md + outputs: + .deepwork/tmp/context_audit.md: + type: file + description: "Audit results for supporting context files: broken links, missing files, syntax errors" + required: true + dependencies: + - check_agent_md + reviews: + - run_each: .deepwork/tmp/context_audit.md + additional_review_guidance: "Read .deepwork/tmp/agent_md_audit.md for context on which files were expected." + quality_criteria: + "References Resolved": "All file references from agent.md are checked for existence." + "Links Valid": "Symlinks and relative paths resolve correctly." + "Syntax Valid": "Referenced files are syntactically valid for their format (YAML, JSON, Markdown, etc.)." + + - id: doctor_report + name: "Doctor Report" + description: "Compile findings from agent.md and context audits into a pass/fail report with remediation instructions." + instructions_file: steps/doctor_report.md + inputs: + - file: .deepwork/tmp/agent_md_audit.md + from_step: check_agent_md + - file: .deepwork/tmp/context_audit.md + from_step: check_context + outputs: + .deepwork/tmp/doctor_report.md: + type: file + description: "Pass/fail report covering agent.md presence, domain declaration, context file integrity, and remediation steps" + required: true + dependencies: + - check_agent_md + - check_context + reviews: + - run_each: .deepwork/tmp/doctor_report.md + quality_criteria: + "All Checks Covered": "Report covers agent.md existence, domain declaration, agent instructions, and context file integrity." + "Pass/Fail Clear": "Each check has a clear pass or fail status." + "Remediation Provided": "Failed checks include specific remediation instructions." + "Repo Job Recommended": "If labels, branch protection, or milestones need attention, the report recommends the repo library job's doctor workflow." diff --git a/src/deepwork/standard_jobs/engineer/requirements.md b/src/deepwork/standard_jobs/engineer/requirements.md new file mode 100644 index 00000000..46494465 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/requirements.md @@ -0,0 +1,103 @@ +# Engineer Job: RFC 2119 Requirements Specification + +This specification defines the normative requirements for the engineer job's +`implement` and `doctor` workflows. The term "engineer" refers to the agent or +human executing the workflow. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119. + +Note: All general version control operations SHALL adhere to the current +established repository standards, beyond the explicit strictures defined below. + +## Implement workflow requirements + +## 1. Product and engineering issue delineation + +The workflow MUST initiate with a high-level Product Issue containing the +overarching user story and functional RFC 2119 requirements. + +An engineer MUST translate this Product Issue into a distinct Engineering Issue. + +The Engineering Issue MUST include the following payloads: the definitive +implementation plan, applicable schematics or CAD snippets, and explicit +definitions of expected red and green test states. + +## 2. Version control initialization + +A dedicated Git worktree or branch MUST be created specifically for the +Engineering Issue. + +The engineer SHALL commit the newly required specifications into the branch +prior to executing implementation code. + +A Pull Request (PR) MUST be opened in a draft state immediately following the +specification commit, strictly utilizing the repository's standardized PR +template. + +## 3. Test-driven execution and verification + +The engineer MUST either implement new failing (red) tests or explicitly verify +current existing tests against the new requirements. + +Each test MUST explicitly reference a specific requirement defined in the +Engineering Issue. + +The engineer SHALL implement the necessary logic, hardware parameters, or +configuration changes to transition the test suite to a passing (green) state. + +## 4. Continuous state synchronization + +The engineer MUST keep the PR checkboxes strictly synchronized with the state of +the active worktree. + +Checkboxes MUST be updated to reflect completion immediately as tasks are +finished and pushed to the remote branch. + +## 5. Artifact generation and continuous integration + +The engineer MUST verify that the CI system produces visual representations of +structural or interface alterations upon a successful green state. These +artifacts MUST include any of the following that are relevant to the domain: +rendered STLs, compiled schematics, localized DOM snapshots, or equivalent +visual artifacts. If the CI system does not produce the expected artifacts, the +engineer MUST document the gap and manually capture equivalents. + +## 6. Pull request finalization and handoff + +The `## Demo` section of the PR MUST display the automatically generated visual +artifacts to facilitate asynchronous review. + +If the implementation unblocks downstream work or requires specific +staging/production verification, the engineer MUST document this in a formal +comment or within the `## Handoff` section of the PR. + +The PR SHALL NOT be merged until peer review validates the visual artifacts and +verifies that all synchronized task checkboxes are complete. + +## 7. Product synchronization + +Upon the successful merge of the PR and closure of the Engineering Issue, the +engineer MUST author a formal comment on the parent Product Issue. + +This comment MUST document the high-level user stories completed and provide +explicit, immutable links to the merged PR(s) and closed Engineering Issue(s), +ensuring product managers maintain up-to-date visibility without parsing +engineering telemetry. + +## Doctor workflow requirements + +## 8. Contextual awareness and the doctor workflow + +To maintain a project-agnostic shared workflow, every repository MUST contain an +agent.md file (or equivalent domain documentation). + +This documentation MUST explicitly define the project's engineering domain (e.g., +AnchorCAD, web application, PCB layout) and instruct the automated agents on how +to parse, build, and test the repository. + +A separate doctor workflow MUST exist and be executed to validate that the +agent.md and related context files are present, correctly linked, and +syntactically valid, ensuring the automation agent knows how to interact with the +repository's specific medium. diff --git a/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md b/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md new file mode 100644 index 00000000..785630fd --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md @@ -0,0 +1,56 @@ +# Check Agent Context File + +Verify that agent.md (or equivalent) exists, declares the engineering domain, provides +build/test/parse instructions, and that CODEOWNERS is configured. + +## Process + +1. **Locate the agent context file** — check common locations at the repository root: + `agent.md`, `AGENT.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`. + Resolve any symlinks. Record which file(s) were found. +2. **Check domain declaration** — the file MUST explicitly define the project's engineering + domain (e.g., web application, CAD/mechanical, firmware/embedded, documentation site) +3. **Check agent instructions** — verify the file contains instructions for: + - **Parse**: How to navigate the codebase (project structure, key files) + - **Build**: How to build or compile the project + - **Test**: How to run the test suite +4. **Check CODEOWNERS** — look in `CODEOWNERS`, `.github/CODEOWNERS`, `docs/CODEOWNERS`. + CODEOWNERS is REQUIRED for automatic reviewer assignment when PRs are undrafted (Req 6). +5. **Check for issues** — empty/stub files, circular symlinks, references to nonexistent files + +## Output Format + +### .deepwork/tmp/agent_md_audit.md + +```markdown +# Agent Context File Audit + +## File Discovery +- File found: yes/no +- Path: [path or "not found"] +- Is symlink: yes/no → [target] + +## Domain Declaration +- Declared: yes/no +- Domain: [domain or "not declared"] + +## Agent Instructions +| Category | Present | Details | +|----------|---------|---------| +| Parse/Navigate | yes/no | [brief or "missing"] | +| Build | yes/no | [brief or "missing"] | +| Test | yes/no | [brief or "missing"] | + +## CODEOWNERS +- File found: yes/no +- Path: [path or "not found"] +- Rules defined: [N or "empty"] + +## Issues +- [list or "none"] + +## Overall Status: [PASS/FAIL] + +## Referenced Files +[list of files to check in next step] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/check_context.md b/src/deepwork/standard_jobs/engineer/steps/check_context.md new file mode 100644 index 00000000..cfbb8f55 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/check_context.md @@ -0,0 +1,40 @@ +# Check Supporting Context Files + +Verify that files referenced by agent.md are present, correctly linked, and syntactically +valid. If agent.md was not found, report that context files cannot be checked. + +## Process + +1. Read `agent_md_audit.md` from the previous step and collect the list of referenced files +2. For each reference: verify it exists, resolve symlinks, check it is non-empty +3. Validate syntax by extension: `.yml`/`.yaml` (valid YAML), `.json` (valid JSON), + `.md` (no broken internal links), `.toml` (valid TOML), `.nix` (balanced braces) +4. Note any unreferenced context files near agent.md (`CONTRIBUTING.md`, `ARCHITECTURE.md`, + `.editorconfig`, `flake.nix`, etc.) as informational — not failures + +## Output Format + +### .deepwork/tmp/context_audit.md + +```markdown +# Context File Audit + +## Source +- Agent context file: [path] +- Agent context status: [PASS/FAIL] + +## Referenced Files + +| # | Path | Exists | Symlink | Syntax | Status | +|---|------|--------|---------|--------|--------| +| 1 | [path] | yes/no | yes→[target]/no | valid/invalid/skipped | PASS/FAIL | + +## Issues +- [list or "none"] + +## Unreferenced Context Files +- [path] — [description] + +## Overall Status: [PASS/FAIL] +- Checked: [N], Passed: [N], Failed: [N] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/doctor_report.md b/src/deepwork/standard_jobs/engineer/steps/doctor_report.md new file mode 100644 index 00000000..8e525833 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/doctor_report.md @@ -0,0 +1,55 @@ +# Doctor Report + +Compile findings from agent.md and context file audits into a pass/fail report with +remediation instructions. Serves two audiences: the developer fixing issues, and the +`implement` workflow checking readiness. + +## Process + +1. Read `agent_md_audit.md` and `context_audit.md`; collect all PASS/FAIL statuses +2. For each failed check, provide: what is wrong, which workflow step would fail, and + specific remediation steps +3. Cross-cutting recommendations: + - If labels/branch protection/milestones need attention, recommend `repo` library job's + `doctor` workflow — do not duplicate that scope + - If CI is not configured, note the impact on artifact generation (Req 5) +4. Determine overall readiness: READY (all pass), NOT READY (critical failures), + or PARTIAL (non-critical issues, implement can proceed with caveats) + +## Output Format + +### .deepwork/tmp/doctor_report.md + +```markdown +# Engineer Doctor Report + +## Overall Status: [READY/NOT READY/PARTIAL] + +## Check Summary + +| # | Check | Status | Details | +|---|-------|--------|---------| +| 1 | Agent context file exists | PASS/FAIL | [detail] | +| 2 | Engineering domain declared | PASS/FAIL | [detail] | +| 3 | Build instructions present | PASS/FAIL | [detail] | +| 4 | Test instructions present | PASS/FAIL | [detail] | +| 5 | Parse/navigate instructions present | PASS/FAIL | [detail] | +| 6 | Referenced files exist | PASS/FAIL | [N/N passed] | +| 7 | Referenced files valid syntax | PASS/FAIL | [N/N passed] | +| 8 | CODEOWNERS file present | PASS/FAIL | [path or "not found"] | + +## Remediation + +### [Check Name] — FAIL +**Problem**: [what is wrong] +**Impact**: [which step would fail] +**Fix**: [specific steps] + +## Recommendations +- [cross-cutting recommendations] + +## Next Steps +- [READY]: Run `engineer/implement` to begin +- [NOT READY]: Fix issues above, re-run `engineer/doctor` +- [PARTIAL]: [caveats] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md new file mode 100644 index 00000000..bd8393dc --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md @@ -0,0 +1,53 @@ +# Finalize PR with Artifacts + +Ensure CI generates visual artifacts, populate the PR `## Demo` section, document handoff +notes, verify all checkboxes are complete, and undraft the PR for review. + +## Process + +1. **Verify CI artifacts** — confirm the pipeline produced domain-appropriate visual artifacts + (DOM snapshots, rendered STLs, logic traces, PDF renders, etc.). If CI does not produce + artifacts, document the gap and manually capture equivalents. +2. **Populate `## Demo`** — add visual artifacts with captions and before/after + comparisons where applicable +3. **Document handoff** — if the implementation unblocks downstream work or needs + staging/production verification, add a `## Handoff` section; otherwise note "none" +4. **Verify checkboxes** — confirm every PR task checkbox is checked and matches the branch state +5. **Undraft and request review**: + - MUST transition the PR from draft to ready-for-review (`gh pr ready [PR-URL]`) + - Code owners (from `CODEOWNERS`) are automatically requested as reviewers — verify this happened + - If the platform lacks automatic code owner assignment, manually request reviewers + - The PR SHALL NOT be merged until peer review validates artifacts and checkboxes + +## Output Format + +### .deepwork/tmp/pr_finalization.md + +```markdown +# PR Finalization + +## CI Status +- Pipeline: [pass/fail/pending] +- Artifacts: [available/not available/manual] + +## Visual Artifacts +| Artifact | Type | Location | +|----------|------|----------| +| [name] | [type] | [URL or path] | + +## Demo Section +- Updated: yes/no +- Artifacts included: [N] + +## Handoff +- Downstream implications: [yes/no] +- Details: [description or "none"] + +## Checkboxes +- Total: [N], Checked: [N], Synchronized: yes/no + +## Review +- PR undrafted: yes/no +- Code owner reviewers requested: [names or "not configured"] +- Base branch up to date: yes/no +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/green_implementation.md b/src/deepwork/standard_jobs/engineer/steps/green_implementation.md new file mode 100644 index 00000000..12f4ab83 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/green_implementation.md @@ -0,0 +1,47 @@ +# Implement to Pass Tests + +Implement the necessary logic, parameters, or configuration to transition all tests from +red to green. Keep PR checkboxes synchronized with progress throughout. + +## Process + +1. Review the implementation plan and test manifest to plan execution order +2. For each task: + - Write the necessary changes + - Run relevant tests to verify red-to-green transition + - Commit: `feat(scope): implement [task description]` + - Push to remote + - **Immediately update the PR checkbox** for the completed task +3. Run the full test suite and confirm all tests pass +4. Verify all PR checkboxes reflect the current branch state + +## Output Format + +### .deepwork/tmp/implementation_summary.md + +```markdown +# Implementation Summary + +## Overview +- Tasks completed: [N]/[total] +- All tests green: yes/no + +## Tasks + +### Task 1: [task name] +- Requirement: Req [N] +- Changes: [files modified/created] +- Test result: PASS +- Commit: [sha] + +## Test Output +[paste of test runner output showing all passes] + +## PR State +- Checkboxes synchronized: yes/no +- Checked: [N]/[total] +- Divergences from plan: [none, or description] + +## Commits +1. [sha] — [message] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md b/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md new file mode 100644 index 00000000..27e74f7a --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md @@ -0,0 +1,39 @@ +# Initialize Branch and Draft PR + +Create a dedicated git branch or worktree for the engineering issue, commit the specification +before any implementation code, and open a draft PR using the repository's PR template. + +## Process + +1. Create a branch based on the latest default branch, following the repository's naming conventions +2. Commit the engineering specification — this MUST happen before any implementation code + - Use a conventional commit: `docs(engineer): add engineering spec for #[issue-number]` +3. Open a draft PR using the repository's standardized template: + - Link the PR to the engineering issue + - Populate the task checklist from the engineering issue's implementation plan +4. Record the branch name, PR URL, and initial commit SHA + +## Output Format + +### .deepwork/tmp/branch_context.md + +```markdown +# Branch Context + +## Version Control +- Branch: [branch-name] +- Base: [default-branch] +- Initial Commit: [sha] + +## Pull Request +- URL: [pr-url] +- State: draft +- Template: [template used] + +## Engineering Issue +- URL: [engineering-issue-url] + +## Task Checklist (from PR) +- [ ] Task 1: [description] +- [ ] Task 2: [description] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/product_sync.md b/src/deepwork/standard_jobs/engineer/steps/product_sync.md new file mode 100644 index 00000000..21a2cbb8 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/product_sync.md @@ -0,0 +1,42 @@ +# Synchronize Product Issue + +After PR merge and engineering issue closure, author a formal comment on the parent +product issue documenting completed user stories with immutable links. + +## Process + +1. **Verify prerequisites** — confirm the PR is merged and the engineering issue is closed. + If either is still open, inform the user and pause — resume via `go_to_step` after merge. +2. Gather immutable links: merged PR URL, closed engineering issue URL, key commit SHAs +3. Summarize which high-level user stories were addressed; note any deferred items +4. Post a formal comment on the parent product issue: + - Which user stories were completed + - Immutable links to merged PR and closed engineering issue + - Any deferred items or follow-up needed + - Written for a product manager audience (no engineering jargon) + +## Output Format + +### .deepwork/tmp/product_sync_record.md + +```markdown +# Product Sync Record + +## Prerequisites +- PR merged: yes/no — [PR URL] +- Engineering issue closed: yes/no — [issue URL] + +## Comment Posted +- Product issue: [URL] +- Timestamp: [ISO 8601] + +## Comment Content +--- +[exact text posted] +--- + +## Traceability +- User stories completed: [list] +- Deferred items: [list or "none"] +- Follow-up needed: [yes/no — description] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/red_tests.md b/src/deepwork/standard_jobs/engineer/steps/red_tests.md new file mode 100644 index 00000000..622e8fa1 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/red_tests.md @@ -0,0 +1,41 @@ +# Write Failing Tests + +Implement new failing (red) tests or verify existing tests against the new requirements. +Each test MUST reference a specific requirement from the engineering issue. All tests MUST +fail before any implementation begins. + +## Process + +1. Review the test definitions from `engineering_issue.md` — identify which tests to create vs. reuse +2. For each requirement, write a new failing test or verify an existing test covers it + - Include a comment or annotation referencing the requirement (e.g., `# Req 3: ...`) +3. Run the test suite and confirm all new/modified tests fail; investigate any unexpected passes +4. Commit tests separately from implementation: `test(scope): add failing tests for #[issue-number]` +5. Push to the remote branch and update PR checkboxes for test-related tasks + +## Output Format + +### .deepwork/tmp/test_manifest.md + +```markdown +# Test Manifest + +## Summary +- Framework: [test framework] +- New tests: [N] +- Verified existing: [N] +- Red state confirmed: yes/no + +## Tests + +| # | Test | File | Requirement | Type | Red State | +|---|------|------|-------------|------|-----------| +| 1 | [test name] | [file:line] | Req [N] | new | FAIL: [reason] | +| 2 | [test name] | [file:line] | Req [N] | existing | FAIL: [reason] | + +## Test Output +[paste of test runner output showing failures] + +## Commits +- [sha] — [commit message] +``` diff --git a/src/deepwork/standard_jobs/engineer/steps/translate_issue.md b/src/deepwork/standard_jobs/engineer/steps/translate_issue.md new file mode 100644 index 00000000..d8054f92 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/translate_issue.md @@ -0,0 +1,49 @@ +# Translate Product Issue to Engineering Issue + +Transform the product issue into a distinct engineering issue with implementation plan, +test definitions (red/green states), and traceability links. + +## Process + +1. Fetch the product issue — extract user story, requirements, acceptance criteria, and constraints +2. Read agent.md to determine the engineering domain and build/test conventions; if missing, warn the user and recommend the `doctor` workflow +3. Draft the engineering issue: + - Definitive implementation plan with actionable tasks + - Red and green test state definitions for each requirement + - Domain-appropriate schematics, code references, or configuration details + - Every product requirement mapped to at least one task +4. Create the issue on the git platform, label as `engineering`, link to parent product issue + +## Output Format + +### .deepwork/tmp/engineering_issue.md + +```markdown +# Engineering Issue: [Title] + +## Parent Product Issue +- URL: [product_issue_url] +- User Story: [one-line summary] + +## Implementation Plan + +### Task 1: [task name] +- Requirement: Req [N] — [requirement summary] +- Description: [what to implement] +- Files: [expected files to create/modify] + +## Test Definitions + +| Test | Requirement | Red State (before) | Green State (after) | +|------|-------------|---------------------|---------------------| +| [test name] | Req [N] | [expected failure] | [expected pass] | + +## Domain Context +- Engineering domain: [from agent.md] +- Build system: [from agent.md] +- Test framework: [from agent.md] +``` + +### .deepwork/tmp/engineering_issue_url.md + +Single-line file containing the URL of the created engineering issue.