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>

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
 

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,7 +30,7 @@ library_job_portability:
   match:
     include:
       - "**/job.yml"
-      - "**/steps/*.md"
+      - "**/conventions.md"
       - "**/readme.md"
       - "**/conventions.md"
       - "**/templates/*.template"
@@ -51,7 +51,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

@@ -3,14 +3,13 @@ job_definition_review:
   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
 

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
 ```