refactor: move workflow workspace from .claude/ to .agent_workspace/

[aireilly]

Summary

• Moves all workflow artifacts (step outputs, progress files, cloned repos, hooks, workflow YAML configs) from .claude/docs/ and .claude/hooks/ to .agent_workspace/
• Claude Code has safety guardrails on .claude/ that trigger permission prompts on every read/write, even with --dangerously-skip-permissions — this eliminates that UX friction
• Adds .agent_workspace/ to .gitignore; bumps docs-tools to v0.0.62

Files changed (21)

Orchestrator core: SKILL.md, 3 default YAMLs, resolve_source.py, setup-hooks.sh, workflow-completion-check.sh, step-result-schema.md

Step skills: docs-workflow-start, -code-evidence, -create-jira, -create-merge-request, -planning, -requirements, -scope-req-audit, -style-review, -tech-review

Docs/meta: README.md, .gitignore, plugin.json, spec doc

Test plan

• Run /docs-orchestrator PROJ-123 and verify step outputs go to .agent_workspace/proj-123/
• Verify setup-hooks.sh installs hook to .agent_workspace/hooks/
• Verify workflow resume reads progress from .agent_workspace/<ticket>/workflow/
• Verify custom workflow YAML is read from .agent_workspace/docs-<name>.yaml
• Confirm no permission prompts from Claude Code guardrails during workflow execution

Closes #141

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated all workflow and skill documentation to reflect new workspace directory structure.

• Chores

  • Migrated workspace directories from .claude/ to .agent_workspace/ across all workflows, scripts, and configurations.
  • Updated workflow completion checks and hook installation paths to use the new workspace location.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ed026bab-889f-4beb-a1aa-83101a5b8872

📥 Commits

Reviewing files that changed from the base of the PR and between d744b8a and 36f128d.

📒 Files selected for processing (20)

• .gitignore
• plugins/docs-tools/README.md
• plugins/docs-tools/skills/docs-orchestrator/SKILL.md
• plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml
• plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-create-jira.yaml
• plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml
• plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh
• plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md
• plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py
• plugins/docs-tools/skills/docs-orchestrator/scripts/setup-hooks.sh
• plugins/docs-tools/skills/docs-workflow-code-evidence/SKILL.md
• plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md
• plugins/docs-tools/skills/docs-workflow-create-merge-request/SKILL.md
• plugins/docs-tools/skills/docs-workflow-planning/SKILL.md
• plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md
• plugins/docs-tools/skills/docs-workflow-scope-req-audit/SKILL.md
• plugins/docs-tools/skills/docs-workflow-start/SKILL.md
• plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md
• plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md
• specs/2026-03-22-docs-workflow-simplification-design.md

---

Walkthrough

This pull request migrates the docs workflow workspace directory structure from .claude/ to .agent_workspace/, updating configuration files, shell and Python scripts, workflow YAML files, and documentation to reference the new directory paths.

Changes

Cohort / File(s)	Summary
Configuration & Ignore .gitignore	Adds .agent_workspace/ directory to ignore patterns.
Documentation & Examples plugins/docs-tools/README.md, plugins/docs-tools/skills/docs-orchestrator/SKILL.md, plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md, plugins/docs-tools/skills/docs-workflow-*/SKILL.md (8 files), specs/2026-03-22-docs-workflow-simplification-design.md	Updates example paths and documentation from .claude/docs/ to .agent_workspace/ across CLI argument descriptions, code samples, and design specifications.
Workflow Definitions plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow*.yaml (3 files)	Updates YAML comments documenting step output directory conventions from .claude/docs/<ticket>/<step-name>/ to .agent_workspace/<ticket>/<step-name>/.
Setup & Installation Scripts plugins/docs-tools/skills/docs-orchestrator/scripts/setup-hooks.sh	Changes hook installation path and settings.json hook command references from .claude/hooks/ to .agent_workspace/hooks/.
Hook Implementation & Resolution plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh, plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py	Modifies workflow-completion-check.sh to detect active workflows via progress JSON files under .agent_workspace/*/workflow/*.json instead of a marker file; updates resolve_source.py CLI help examples to reference new base path location.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• refactor: move workflow workspace from .claude/ to .agent_workspace/ #142 — Implements the same workspace migration from .claude/ to .agent_workspace/, updating the same set of files including .gitignore, SKILL documentation, and orchestrator scripts.
• fix: scope Stop hook to active workflow only #139 — Modifies the workflow-completion-check.sh stop-hook to change how active workflows are detected, directly overlapping with the hook changes in this PR.
• feat: add docs-workflow-start interactive launcher skill #95 — Updates docs-workflow-start skill and related workspace path conventions, including files modified in this PR.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (2 errors, 1 warning)

Check name	Status	Explanation	Resolution
Git Safety Rules	❌ Error	File create_merge_request.sh contains unsafe git operations: hardcoded 'origin' remote name without discovery, --force-with-lease push without user confirmation, and force-push violations.	Remove force-with-lease push or require explicit user confirmation. Implement dynamic remote discovery using 'git remote -v' instead of hardcoded 'origin' references.
Plugin Registry Consistency	❌ Error	marketplace.json lacks version fields for plugins while plugin.json files specify versions, creating inconsistency between registry and manifests.	Add version fields to marketplace.json entries matching their plugin.json versions: docs-tools 0.0.62, hello-world 1.0.1, vale-tools 0.0.1, dita-tools 0.0.12, jtbd-tools 1.1.3, cqa-tools 1.0.5, rhivos-tools 1.0.4.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (7 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor: move workflow workspace from .claude/ to .agent_workspace/' accurately and concisely describes the primary change: migrating all workflow artifacts from .claude/ to .agent_workspace/ directory.
Linked Issues check	✅ Passed	The PR completely implements all coding requirements from issue #141: migrates paths from .claude/ to .agent_workspace/, updates all referenced files (orchestrator core, step skills, scripts), adds .agent_workspace/ to .gitignore, and bumps version to 0.0.62.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the workspace migration objective defined in #141; no unrelated modifications to Claude Code config, logic, or unrelated features are present.
No Real People Names In Style References	✅ Passed	A comprehensive search of all 21 modified files found no references to real people's names in style contexts, plugin commands, or documentation.
No Untrusted Mcp Servers	✅ Passed	No MCP server installations from untrusted sources detected. All changes are path redirections and documentation updates with no new external dependencies.
Skill And Script Conventions	✅ Passed	PR maintains consistent skill and script conventions with bare names for within-plugin references, correct relative paths for co-located scripts, and preserved existing qualified names.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/move-workspace-from-claude-dir

---

_{Review rate limit: 8/10 reviews remaining, refill in 6 minutes and 1 second.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🚀 Deployed on https://69f524e785e009814dcca675--redhat-docs-agent-tools.netlify.app