refactor: deprecate steps/ folder pattern in job definitions (#367)

* refactor: deprecate steps/ folder pattern in job definitions

Step instructions are now inlined in job.yml. This removes all references
to the steps/ folder pattern across documentation, AGENTS.md files,
.deepreview rules, CI tests, and job instructions. Supplemental reference
files are moved from steps/ to the job root directory.

The repair workflow retains steps/ references for migrating legacy jobs,
and now instructs agents to `git rm` step instruction files after inlining.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review findings — remove duplicate pattern, update .deepreview instructions

- Remove duplicate `**/conventions.md` in library/jobs/.deepreview include list
- Update engineer/.deepreview and template.deepreview to reference inline
  step instructions instead of deprecated step instruction files
- Add changelog entry for steps/ deprecation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: update engineer .deepreview description to reflect inline instructions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nhorton

.deepwork/jobs/test_job_flow/AGENTS.md

@@ -13,9 +13,7 @@ This folder and its subfolders are managed using `deepwork_jobs` workflows.
 ```
 .
 ├── AGENTS.md          # This file - project context and guidance
-├── job.yml            # Job specification (created by define step)
-├── steps/             # Step instruction files (created by implement step)
-│   └── *.md           # One file per step
+├── job.yml            # Job specification with inline step instructions
 ├── hooks/             # Custom validation scripts and prompts
 │   └── *.md|*.sh      # Hook files referenced in job.yml
 ├── scripts/           # Reusable scripts and utilities created during job execution

.deepwork/jobs/test_job_flow/job.yml

@@ -90,8 +90,8 @@ workflows:
              completed on first try or required retries.
 
           2. **Verify completion**: Confirm `.deepwork/jobs/detailed_test_review/job.yml`
-             exists with expected structure (2 steps, correct outputs, reviews). Check
-             step instruction files exist in `steps/`.
+             exists with expected structure (2 steps, correct outputs, reviews, and
+             inline step instructions).
 
           3. **Identify friction points**: Look for errors, workarounds, retries, confusion,
              unnecessary steps, slow paths, and missing guidance in the transcript.

.deepwork/learning-agents/consistency-reviewer/core-knowledge.md

@@ -34,7 +34,7 @@ There are exactly three types of jobs. Confusing them is one of the most common
 ### Key File Patterns
 
 - `job.yml` — Job definitions with steps, workflows, outputs, reviews, quality criteria
-- `steps/*.md` — Step instruction files (markdown with structured guidance)
+- Step instructions are inlined in `job.yml` (the `steps/` folder pattern is deprecated)
 - `hooks/` — Lifecycle hooks (after_agent, before_tool, etc.)
 - `.claude/agents/*.md` — Agent definitions with YAML frontmatter (name, description)
 - `AGENTS.md` — Bespoke learnings and context for a working directory

.github/workflows/claude-code-test.yml

@@ -310,18 +310,12 @@ jobs:
             exit 1
           fi
 
-          # Verify step files were created
-          echo "=== Checking step files were created ==="
-          if [ -f ".deepwork/jobs/fruits/steps/identify.md" ] && [ -f ".deepwork/jobs/fruits/steps/classify.md" ]; then
-            echo "SUCCESS: Step instruction files created"
-            echo "--- identify.md ---"
-            cat .deepwork/jobs/fruits/steps/identify.md
-            echo ""
-            echo "--- classify.md ---"
-            cat .deepwork/jobs/fruits/steps/classify.md
+          # Verify step instructions are inlined in job.yml
+          echo "=== Checking step instructions are inlined ==="
+          if grep -q 'instructions:' .deepwork/jobs/fruits/job.yml; then
+            echo "SUCCESS: Step instructions are inlined in job.yml"
           else
-            echo "ERROR: Step files were not created"
-            ls -la .deepwork/jobs/fruits/steps/ || echo "No steps directory"
+            echo "ERROR: No inline step instructions found in job.yml"
             exit 1
           fi
 

CHANGELOG.md

@@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Deprecated the `steps/` folder pattern for job definitions — step instructions are now inlined in `job.yml`; moved supplemental reference files from `steps/` to job root directories
+- Repair workflow now instructs agents to `git rm` step instruction files after inlining
+
 ### Fixed
 
 ### Removed

doc/doc-specs.md

@@ -93,7 +93,8 @@ steps:
   - id: generate_report
     name: "Generate Monthly Report"
     description: "Create the monthly AWS spending report"
-    instructions_file: steps/generate_report.md
+    instructions: |
+      Generate the monthly AWS spending report...
     outputs:
       - file: reports/aws_spending.md
         doc_spec: .deepwork/doc_specs/monthly_aws_report.md

library/jobs/.deepreview

@@ -30,9 +30,8 @@ library_job_portability:
   match:
     include:
       - "**/job.yml"
-      - "**/steps/*.md"
-      - "**/readme.md"
       - "**/conventions.md"
+      - "**/readme.md"
       - "**/templates/*.template"
     exclude:
       - ".deepreview"
@@ -51,7 +50,7 @@ library_job_portability:
       - Workspace-relative paths that assume a specific repo layout
         (e.g., `.repos/acme/api/` or `/code/myproject/`)
 
-      Acceptable: relative paths within the job directory (e.g., `steps/foo.md`,
+      Acceptable: relative paths within the job directory (e.g., `templates/bar.yml`,
       `templates/bar.yml`) and generic placeholders like `<project_root>`.
 
       ## Personal and Private Information

library/jobs/README.md

@@ -74,49 +74,22 @@ library/jobs/
 │   ├── job.yml
 │   ├── AGENTS.md            # Agent context and learnings
 │   ├── CLAUDE.md -> AGENTS.md
-│   ├── requirements.md      # RFC 2119 requirements specification
-│   └── steps/               # Step instruction files (also inlined in job.yml)
+│   └── requirements.md      # RFC 2119 requirements specification
 ├── platform_engineer/       # Platform engineering workflows
 │   ├── job.yml
 │   ├── AGENTS.md            # Agent context and learnings
 │   ├── CLAUDE.md -> AGENTS.md
 │   ├── conventions.md       # RFC 2119 platform engineering standards
 │   ├── readme.md
-│   ├── steps/               # Step instruction files (also inlined in job.yml)
 │   └── templates/           # Output templates
 ├── repo/
-│   ├── job.yml              # Job definition (name, steps, workflows)
-│   ├── readme.md            # Job-specific documentation
-│   └── steps/
-│       ├── detect_platform.md
-│       ├── ensure_labels.md
-│       ├── check_branch_protection.md
-│       ├── check_milestones.md
-│       ├── check_boards.md
-│       ├── setup_report.md
-│       ├── audit_labels.md
-│       ├── audit_branch_protection.md
-│       ├── audit_milestones.md
-│       ├── audit_boards.md
-│       └── doctor_report.md
+│   ├── job.yml              # Job definition (self-contained with inline instructions)
+│   └── readme.md            # Job-specific documentation
 ├── research/
-│   ├── job.yml              # Job definition (name, steps, workflows)
+│   ├── job.yml              # Job definition (self-contained with inline instructions)
 │   ├── readme.md            # Job-specific documentation
 │   ├── AGENTS.md            # Agent context and learnings
-│   ├── CLAUDE.md -> AGENTS.md
-│   └── steps/
-│       ├── scope.md
-│       ├── choose_platforms.md
-│       ├── gather.md
-│       ├── gather_quick.md
-│       ├── synthesize.md
-│       ├── summarize.md
-│       ├── report.md
-│       ├── parse.md
-│       ├── file.md
-│       ├── ingest_material.md
-│       ├── analyze.md
-│       └── plan.md
+│   └── CLAUDE.md -> AGENTS.md
 └── spec_driven_development/
     ├── job.yml              # Job definition (self-contained with inline instructions)
     └── readme.md            # Job-specific documentation
@@ -147,7 +120,7 @@ The job definition file contains:
     - `process_requirements`: Optional quality criteria for the work process
   - `post_workflow_instructions`: Optional instructions shown after workflow completes
 
-Step instructions are inlined in `job.yml`. Some jobs also retain separate `steps/*.md` files from earlier versions; the inline `instructions` in `job.yml` are the canonical source.
+Step instructions are inlined in `job.yml` using YAML block scalars (`instructions: |`).
 
 ## Using a Job from the Library
 

library/jobs/engineer/.deepreview

@@ -1,16 +1,15 @@
 job_definition_review:
-  description: "Review job.yml, requirements.md, and step instructions for correctness, completeness, and coherence as a holistic workflow."
+  description: "Review job.yml (with inline step instructions) and requirements.md 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.
+      Review this DeepWork job definition (job.yml) and its requirements (requirements.md)
+      holistically. Check that they form a coherent, well-structured workflow that an AI
+      agent can execute reliably.
 
       ## Reference Material
 
@@ -42,13 +41,13 @@ job_definition_review:
       - 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
+      ### 4. Inline Step Instructions
+      - Every step defined in job.yml has inline `instructions:` content
       - 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
+      - If there is duplicated content amongst step instructions, it should be moved to `common_job_info_provided_to_all_steps_at_runtime`
+      - If there is content that is needed in multiple steps but not all, it should be moved to a shared file in the job directory and referenced in the steps
 
       ### 5. Quality Reviews
       - Steps with complex or final outputs have reviews defined
@@ -58,8 +57,8 @@ job_definition_review:
       - 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.
+      - Each step's inline instructions follow 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.

library/jobs/engineer/AGENTS.md

@@ -11,18 +11,8 @@ It is a library job — available for users to adopt but not auto-installed by t
 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
+├── job.yml                # Job definition (all step instructions inlined)
+└── requirements.md        # RFC 2119 requirements specification
 ```
 
 ## Workflows