refactor: deprecate steps/ folder pattern in job definitions

.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

library/jobs/platform_engineer/AGENTS.md

@@ -19,7 +19,6 @@ platform_engineer/
 ├── conventions.md       # RFC 2119 platform engineering standards
 ├── readme.md            # User-facing documentation
 ├── AGENTS.md            # This file — agent context and learnings
-├── steps/               # Step instruction files
 └── templates/           # Output templates
 ```
 

library/jobs/research/AGENTS.md

@@ -19,28 +19,15 @@ into their project's `.deepwork/jobs/` directory.
 research/
 ├── AGENTS.md              # This file
 ├── CLAUDE.md              # Symlink to AGENTS.md
-├── job.yml                # Job definition with 4 workflows
-├── readme.md              # User-facing documentation
-└── steps/
-    ├── scope.md           # Define research scope (shared: deep + quick)
-    ├── choose_platforms.md # Select AI platforms (deep only)
-    ├── gather.md          # Gather sources, 8+ (deep)
-    ├── gather_quick.md    # Gather sources, 3+ (quick)
-    ├── synthesize.md      # Synthesize findings (deep)
-    ├── summarize.md       # Synthesize + report in one step (quick)
-    ├── report.md          # Write final report (deep)
-    ├── parse.md           # Parse external material (ingest)
-    ├── file.md            # File to notes directory (ingest)
-    ├── ingest_material.md # Nested ingest workflow entry (reproduce)
-    ├── analyze.md         # Analyze reproducibility (reproduce)
-    └── plan.md            # Create reproduction plan (reproduce)
+├── job.yml                # Job definition with 4 workflows (all step instructions inlined)
+└── readme.md              # User-facing documentation
 ```
 
 ## Editing Guidelines
 
 - Source of truth is `library/jobs/research/`
 - Edit files here directly — changes benefit all adopters
-- Step instruction files live in `steps/` and are referenced by `instructions_file` in job.yml
+- Step instructions are inlined in job.yml
 
 ## Workflows
 

src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md

@@ -22,13 +22,7 @@ deepwork_jobs/
 ├── AGENTS.md              # This file
 ├── job.yml                # Job definition
 ├── make_new_job.sh        # Script to create new job structure
-├── steps/
-│   ├── define.md          # Define step instructions
-│   ├── implement.md       # Implement step instructions
-│   ├── test.md            # Test step instructions
-│   ├── iterate.md         # Iterate step instructions
-│   ├── learn.md           # Learn step instructions
-│   └── supplemental_file_references.md  # Reference documentation
+├── supplemental_file_references.md  # Reference documentation for job.yml fields
 └── templates/
     ├── job.yml.template              # Job spec structure
     ├── step_instruction.md.template  # Step instruction structure