Skip to content

Refactor job.yml format: inline steps, step_arguments, DeepWork Reviews#256

Draft
nhorton wants to merge 7 commits intoclaude/remove-runner-arg-oc2v7from
job_yml_refactor
Draft

Refactor job.yml format: inline steps, step_arguments, DeepWork Reviews#256
nhorton wants to merge 7 commits intoclaude/remove-runner-arg-oc2v7from
job_yml_refactor

Conversation

@nhorton
Copy link
Contributor

@nhorton nhorton commented Mar 9, 2026

Summary

  • Unify job.yml around workflows with inline steps, replacing the old two-level format (root steps[] + workflows referencing step IDs)
  • Replace bespoke ClaudeCLI quality gate with DeepWork Reviews infrastructure (dynamic ReviewRules from job.yml + .deepreview rules)
  • Introduce step_arguments[] as shared data vocabulary (string/file_path) flowing between steps with optional review blocks and json_schema validation
  • Migrate all 3 standard jobs and 1 library job to new format with instructions inlined (delete all steps/*.md files)
  • Remove: version field, root-level steps[], dependencies, hooks, exposed/hidden, instructions_file, concurrent step groups, ClaudeCLI module, --external-runner flag

Test plan

  • 627 tests pass (1 skipped e2e, 1 xfailed unimplemented)
  • ruff clean, mypy clean
  • All 3 standard jobs + library job parse with new parser
  • Run a workflow end-to-end via MCP to verify runtime behavior
  • Verify .deepreview rules fire correctly on step outputs
  • Test sub_workflow invocation across jobs

🤖 Generated with Claude Code

claude and others added 7 commits March 8, 2026 23:27
State now survives `claude -r` restarts by using the Claude Code
session_id as the storage key and persisting all state to disk at
.deepwork/tmp/sessions/<platform>/session-<id>/state.json.

- Add startup_context.sh hook to inject CLAUDE_CODE_SESSION_ID and
  CLAUDE_CODE_AGENT_ID into agent context on SessionStart/SubagentStart
- Make session_id required on all MCP tool inputs (start_workflow,
  finished_step, abort_workflow, go_to_step)
- Rewrite StateManager to always read/write from disk (no in-memory cache)
- Support sub-agent isolation via per-agent state files (agent_<id>.json)
- Sub-agent get_stack returns main stack + agent stack for parent visibility
- Update CLI get-stack command for new state file structure

https://claude.ai/code/session_01FXUDZxh1voeeEimkTfBeZm
…ilename collision

- Fix startup_context.sh \n literal producing backslash-n instead of newline
- Make state writes atomic via tempfile + os.replace() for crash resilience
- Include workflow_name in quality review filename to prevent collisions
- Fix _list_sessions_sync docstring to match actual behavior
- Update JOBS-REQ-003 requirements to match new persistent state architecture
- Update JOBS-REQ-001 tool signatures (session_id required, agent_id optional)
- Add tests for crash resilience, atomic writes, and invalid JSON handling
- Add .deepreview rule for requirement file format validation
- Update all test requirement tags to match new numbering scheme

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds a shell function wrapper that passes --plugin-dir for both
plugins/claude and learning_agents directories automatically.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
direnv cannot export shell functions, so the previous approach of wrapping
claude via `export -f` didn't work reliably. Replace with a wrapper script
in .venv/bin/ and add that to PATH via .envrc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove instance_id from MCP interface (unused metadata)
- Fix stale/misplaced requirement traceability comments in tests
- Add missing traceability comments for JOBS-REQ-003.15 (async safety)
- Add PLUG-REQ-001.12 requirement for startup_context.sh hook
- Update doc/mcp_interface.md and doc/architecture.md for session_id
  (now required), agent_id, and new state persistence paths
- Add nix_claude_wrapper deepreview rule to protect plugin-dir flags
- Update CLAUDE.md hooks listing with startup_context.sh

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ws quality gate

Unify the job.yml format around workflows as the primary structure with inline
steps, replacing the old two-level format (root steps[] + workflows referencing
step IDs) and the bespoke ClaudeCLI quality gate.

Key changes:
- step_arguments[] define shared data vocabulary (string/file_path) flowing between steps
- workflows{} are objects with inline steps (no separate step .md files)
- Quality gate uses DeepWork Reviews infrastructure instead of Claude CLI subprocess
- review blocks on step_arguments/outputs create dynamic ReviewRules at runtime
- process_quality_attributes review work_summary against criteria
- json_schema on step_arguments validates file outputs before reviews
- notes → work_summary, current_entry_index → current_step_index
- Removed: version field, root-level steps[], dependencies, hooks, exposed/hidden,
  instructions_file, concurrent step groups, ClaudeCLI module, --external-runner flag

All 3 standard jobs and library job migrated with instructions inlined.
627 tests pass, ruff clean, mypy clean.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@nhorton nhorton changed the base branch from main to claude/remove-runner-arg-oc2v7 March 10, 2026 03:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants