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

.gitignore

@@ -11,6 +11,8 @@ __pycache__/
 *.pyc
 .work/
 *-workspace/
+# Workflow workspace (step outputs, progress files, cloned repos)
+.agent_workspace/
 
 # Auto-generated docs (built by CI, not tracked in source)
 docs/plugins.md

plugins/docs-tools/README.md

@@ -44,19 +44,19 @@ The docs orchestrator (`/docs-orchestrator`) runs a YAML-defined step list. You
 
 The orchestrator looks for workflow YAML in this order:
 
-1. `.claude/docs-<name>.yaml` — if `--workflow <name>` is passed
-2. `.claude/docs-workflow.yaml` — project-level default (when no `--workflow` is specified)
+1. `.agent_workspace/docs-<name>.yaml` — if `--workflow <name>` is passed
+2. `.agent_workspace/docs-workflow.yaml` — project-level default (when no `--workflow` is specified)
 3. Plugin default — `skills/docs-orchestrator/defaults/docs-workflow.yaml`
 
 To customize, download the default into your docs repo and edit it:
 
 ```bash
-mkdir -p .claude
+mkdir -p .agent_workspace
 curl -sL https://raw.githubusercontent.com/redhat-documentation/redhat-docs-agent-tools/main/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml \
-   -o .claude/docs-workflow.yaml
+   -o .agent_workspace/docs-workflow.yaml
 ```
 
-Then modify `.claude/docs-workflow.yaml` to add, remove, or reorder steps:
+Then modify `.agent_workspace/docs-workflow.yaml` to add, remove, or reorder steps:
 
 ```yaml
 workflow:
@@ -116,10 +116,10 @@ This step only runs when `--create-merge-request` is passed to the orchestrator.
 Use `--workflow <name>` to maintain different workflows for different purposes:
 
 ```bash
-# Uses .claude/docs-quick.yaml
+# Uses .agent_workspace/docs-quick.yaml
 /docs-orchestrator PROJ-123 --workflow quick
 
-# Uses .claude/docs-full.yaml
+# Uses .agent_workspace/docs-full.yaml
 /docs-orchestrator PROJ-123 --workflow full
 ```
 
@@ -159,9 +159,9 @@ Compared to the default workflow, the code-evidence variant produces documentati
 To use this workflow without the plugin default, download it into your docs repo:
 
 ```bash
-mkdir -p .claude
+mkdir -p .agent_workspace
 curl -sL https://raw.githubusercontent.com/redhat-documentation/redhat-docs-agent-tools/main/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml \
-   -o .claude/docs-workflow-code-evidence.yaml
+   -o .agent_workspace/docs-workflow-code-evidence.yaml
 ```
 
 ## Starting a docs workflow
@@ -262,7 +262,7 @@ Multiple `--pr` flags can be passed. The requirements analyst will read the PR d
 | `--mkdocs` | Generate Material for MkDocs Markdown instead of AsciiDoc |
 | `--repo-path <path>` | Write files to a specific repo path (e.g., an external clone) |
 | `--create-jira <PROJECT>` | Create a linked JIRA ticket in the specified project |
-| `--workflow <name>` | Use `.claude/docs-<name>.yaml` instead of the default workflow |
+| `--workflow <name>` | Use `.agent_workspace/docs-<name>.yaml` instead of the default workflow |
 
 ### Resuming a workflow
 

plugins/docs-tools/skills/docs-orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-orchestrator
-description: Documentation workflow orchestrator. Reads the step list from .claude/docs-workflow.yaml (or the plugin default). Runs steps sequentially, manages progress state, handles iteration and confirmation gates. Claude is the orchestrator — the YAML is a step list, not a workflow engine.
+description: Documentation workflow orchestrator. Reads the step list from .agent_workspace/docs-workflow.yaml (or the plugin default). Runs steps sequentially, manages progress state, handles iteration and confirmation gates. Claude is the orchestrator — the YAML is a step list, not a workflow engine.
 
 argument-hint: <ticket> [--workflow <name>] [--pr <url>...] [--source-code-repo <url-or-path>...] [--mkdocs] [--draft] [--docs-repo-path <path>] [--create-jira <PROJECT>] [--create-merge-request]
 
@@ -30,12 +30,12 @@ bash ${CLAUDE_SKILL_DIR}/scripts/setup-hooks.sh
 When displaying available options to the user (e.g., on skill load or when asking for flags), reproduce the descriptions below **verbatim** — do not summarize or paraphrase them.
 
 - `$1` — JIRA ticket ID (required). If missing, STOP and ask the user.
-- `--workflow <name>` — Use `.claude/docs-<name>.yaml` instead of `docs-workflow.yaml`. Allows running alternative pipelines (e.g., writing-only, review-only). Falls back to the plugin default at `skills/docs-orchestrator/defaults/docs-workflow.yaml` if no project-level YAML exists
+- `--workflow <name>` — Use `.agent_workspace/docs-<name>.yaml` instead of `docs-workflow.yaml`. Allows running alternative pipelines (e.g., writing-only, review-only). Falls back to the plugin default at `skills/docs-orchestrator/defaults/docs-workflow.yaml` if no project-level YAML exists
 - `--pr <url>...` — PR/MR URLs (space-delimited, one or more). Accepts GitHub PRs (`gh` CLI) and GitLab MRs (`glab` CLI). Used both as requirements input (agent reads diffs/descriptions) and for source repo resolution (repo URL and branch derived from the first PR/MR). When multiple PRs from different repos are provided, all repos are resolved and treated equally as source material
 - `--mkdocs` — Use Material for MkDocs format instead of AsciiDoc. Propagates to the writing step (generates `.md` with MkDocs front matter) and style-review step (applies Markdown-appropriate rules). Sets `options.format` to `"mkdocs"` in the progress file
-- `--draft` — Write documentation to the staging area (`.claude/docs/<ticket>/writing/`) instead of directly into the repo. Uses DRAFT placement mode: no framework detection, no file placement into the target repo. Without this flag, UPDATE-IN-PLACE is the default
+- `--draft` — Write documentation to the staging area (`.agent_workspace/<ticket>/writing/`) instead of directly into the repo. Uses DRAFT placement mode: no framework detection, no file placement into the target repo. Without this flag, UPDATE-IN-PLACE is the default
 - `--docs-repo-path <path>` — Target documentation repository for UPDATE-IN-PLACE mode. The docs-writer explores this directory for framework detection (Antora, MkDocs, Docusaurus, etc.) and writes files there instead of the current working directory. Propagates to `writing` and `create-merge-request` steps (mapped to their internal `--repo-path` flag). **Precedence**: if both `--docs-repo-path` and `--draft` are passed, `--docs-repo-path` wins — log a warning and ignore `--draft`
-- `--source-code-repo <url-or-path>...` — Source code repository/repositories for code evidence and requirements enrichment (space-delimited, one or more). Accepts remote URLs (https://, git@, ssh:// — each shallow-cloned to `.claude/docs/<ticket>/code-repo/<repo_name>/`) or local paths (used directly). The first repo is treated as primary; additional repos are returned as `additional_repos` in the result. Passed to requirements, code-evidence, writing, and technical-review steps (mapped to their internal `--repo` flag). Without `--pr`, the entire repo is the subject matter; with `--pr`, the PR branch is checked out on the primary repo so code-evidence reflects the PR's state. Takes highest priority in source resolution, overriding `source.yaml` and PR-derived URLs
+- `--source-code-repo <url-or-path>...` — Source code repository/repositories for code evidence and requirements enrichment (space-delimited, one or more). Accepts remote URLs (https://, git@, ssh:// — each shallow-cloned to `.agent_workspace/<ticket>/code-repo/<repo_name>/`) or local paths (used directly). The first repo is treated as primary; additional repos are returned as `additional_repos` in the result. Passed to requirements, code-evidence, writing, and technical-review steps (mapped to their internal `--repo` flag). Without `--pr`, the entire repo is the subject matter; with `--pr`, the PR branch is checked out on the primary repo so code-evidence reflects the PR's state. Takes highest priority in source resolution, overriding `source.yaml` and PR-derived URLs
 - `--create-jira <PROJECT>` — Create a linked JIRA ticket in the specified project after the planning step completes. Runs the standalone `docs-workflow-create-jira` workflow (use `--workflow workflow-create-jira`). Requires `JIRA_API_TOKEN` to be set
 - `--create-merge-request` — Create a branch, commit, push, and open a merge request or pull request after reviews complete. Activates the `create-merge-request` workflow step (guarded by `when: create_merge_request`). Off by default
 
@@ -108,7 +108,7 @@ The script outputs JSON to stdout:
 ```json
 {
   "status": "resolved",
-  "repo_path": ".claude/docs/proj-123/code-repo/operator",
+  "repo_path": ".agent_workspace/proj-123/code-repo/operator",
   "repo_url": "https://github.com/org/operator",
   "ref": "pr-branch-name",
   "scope": null
@@ -130,7 +130,7 @@ If `discovered_repos` is present in the result (multiple repos found), log all r
 Writers can create `<base-path>/source.yaml` before starting a workflow to pre-configure the source repo and scope. The script also writes this file after a successful clone so that resume picks it up automatically.
 
 ```yaml
-# .claude/docs/<ticket>/source.yaml
+# .agent_workspace/<ticket>/source.yaml
 repo: https://github.com/org/operator   # URL or local path (required)
 ref: main                                # branch, tag, or commit (default: HEAD)
 scope:
@@ -150,8 +150,8 @@ All fields except `repo` are optional. If `scope` is omitted, the entire reposit
 
 ### 1. Determine the YAML file
 
-- If `--workflow <name>` was specified → `.claude/docs-<name>.yaml`
-- Otherwise → `.claude/docs-workflow.yaml`
+- If `--workflow <name>` was specified → `.agent_workspace/docs-<name>.yaml`
+- Otherwise → `.agent_workspace/docs-workflow.yaml`
 - If the project-level file doesn't exist → fall back to the plugin default at `skills/docs-orchestrator/defaults/docs-workflow.yaml`
 
 ### 2. Read the YAML
@@ -162,7 +162,7 @@ Read the YAML file and extract the ordered step list. Each step has: `name`, `sk
 
 If the YAML includes a top-level `workflow.requires` list, check each condition **before evaluating steps or running anything**:
 
-- `has_source_repo` → a source repo must be resolvable. The pre-flight resolution script tries all sources in priority order: CLI `--source-code-repo`, `source.yaml`, `--pr`-derived, and JIRA ticket discovery (git links and auto-discovered PRs). If **none** yield a source repo, **STOP** immediately with: `"This workflow requires a source code repository. No repo could be discovered from the JIRA ticket. Options: (1) re-run with --source-code-repo <url-or-path>, (2) re-run with --pr <url>, (3) create .claude/docs/<ticket>/source.yaml with a repo: field, or (4) link PRs to the JIRA ticket and re-run."`
+- `has_source_repo` → a source repo must be resolvable. The pre-flight resolution script tries all sources in priority order: CLI `--source-code-repo`, `source.yaml`, `--pr`-derived, and JIRA ticket discovery (git links and auto-discovered PRs). If **none** yield a source repo, **STOP** immediately with: `"This workflow requires a source code repository. No repo could be discovered from the JIRA ticket. Options: (1) re-run with --source-code-repo <url-or-path>, (2) re-run with --pr <url>, (3) create .agent_workspace/<ticket>/source.yaml with a repo: field, or (4) link PRs to the JIRA ticket and re-run."`
 
 Unlike `when` (which makes individual steps conditional), `requires` is a workflow-level precondition — the entire workflow fails if a required condition is not met. This prevents users from running a code-evidence workflow without a repo and only discovering the problem after requirements and planning have already completed.
 
@@ -214,7 +214,7 @@ The orchestrator validates at load time that every step name in `inputs` exists
 Every step writes to a predictable folder based on the ticket ID and step name:
 
 ```
-.claude/docs/<ticket>/<step-name>/
+.agent_workspace/<ticket>/<step-name>/
 ```
 
 The ticket ID is converted to **lowercase** for directory names (e.g., `PROJ-123` → `proj-123`).
@@ -224,15 +224,15 @@ The ticket ID is converted to **lowercase** for directory names (e.g., `PROJ-123
 Resolve the base path to an absolute path so agents (which may run in a different working directory) can locate files correctly:
 
 ```bash
-BASE_PATH="$(cd "$(git rev-parse --show-toplevel)" && pwd)/.claude/docs/${TICKET_LOWER}"
+BASE_PATH="$(cd "$(git rev-parse --show-toplevel)" && pwd)/.agent_workspace/${TICKET_LOWER}"
 ```
 
 Use this absolute `BASE_PATH` for the progress file's `base_path` field and for all `--base-path` arguments passed to step skills.
 
 ### Folder structure
 
 ```
-.claude/docs/proj-123/
+.agent_workspace/proj-123/
   source.yaml                        (per-ticket source config, if applicable)
   code-repo/
     <repo-name>/                     (each repo gets its own subdirectory)
@@ -267,7 +267,7 @@ Use this absolute `BASE_PATH` for the progress file's `base_path` field and for
     docs-workflow_proj-123.json
 ```
 
-Each step skill knows its own output folder and writes there. Each step reads input from upstream step folders referenced in its `inputs` list. The orchestrator passes the base path `.claude/docs/<ticket>/` — step skills derive everything else by convention.
+Each step skill knows its own output folder and writes there. Each step reads input from upstream step folders referenced in its `inputs` list. The orchestrator passes the base path `.agent_workspace/<ticket>/` — step skills derive everything else by convention.
 
 ### Step result sidecars
 
@@ -277,7 +277,7 @@ Every step that produces markdown output also writes a `step-result.json` sideca
 
 Claude writes the progress file directly using the Write tool. Create it after parsing arguments, before step 1. Update it after each step. Also write the active workflow marker at the same time (see [Active workflow marker](#active-workflow-marker)).
 
-**Location**: `.claude/docs/<ticket>/workflow/<workflow-type>_<ticket>.json`
+**Location**: `.agent_workspace/<ticket>/workflow/<workflow-type>_<ticket>.json`
 
 The `workflow_type` field and filename prefix match the YAML's `workflow.name`. This allows multiple workflow types to run against the same ticket without conflict.
 
@@ -287,7 +287,7 @@ The `workflow_type` field and filename prefix match the YAML's `workflow.name`.
 {
   "workflow_type": "<workflow.name from YAML>",
   "ticket": "<TICKET>",
-  "base_path": "/absolute/path/to/.claude/docs/<ticket>",
+  "base_path": "/absolute/path/to/.agent_workspace/<ticket>",
   "status": "in_progress",
   "created_at": "<ISO 8601>",
   "updated_at": "<ISO 8601>",
@@ -310,7 +310,7 @@ The `workflow_type` field and filename prefix match the YAML's `workflow.name`.
 }
 ```
 
-The `output` field records the step's output folder path (e.g., `.claude/docs/proj-123/writing/`) once completed.
+The `output` field records the step's output folder path (e.g., `.agent_workspace/proj-123/writing/`) once completed.
 
 The `result` field stores selected sidecar data after each step completes. This lets the orchestrator make downstream decisions and display summaries without re-reading sidecar files from disk — especially important on resume. Set to `null` until the step completes; then populated from `step-result.json` (see [Step-specific post-processing](#step-specific-post-processing)).
 
@@ -372,7 +372,7 @@ If the user starts a new workflow (different ticket or different workflow type)
 
 ## Check for existing work
 
-Before starting, check for a progress file at `.claude/docs/<ticket>/workflow/<workflow-type>_<ticket>.json`.
+Before starting, check for a progress file at `.agent_workspace/<ticket>/workflow/<workflow-type>_<ticket>.json`.
 
 **If a progress file exists:**
 

plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml

@@ -5,7 +5,7 @@ workflow:
   requires:
     - has_source_repo
 
-  # All step outputs go to: .claude/docs/<ticket>/<step-name>/
+  # All step outputs go to: .agent_workspace/<ticket>/<step-name>/
   # Each step reads its inputs from upstream step folders by convention.
   steps:
     - name: requirements

plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-create-jira.yaml

@@ -2,7 +2,7 @@ workflow:
   name: docs-workflow-create-jira
   description: Analyze requirements, create a documentation plan, and create a linked JIRA ticket.
 
-  # All step outputs go to: .claude/docs/<ticket>/<step-name>/
+  # All step outputs go to: .agent_workspace/<ticket>/<step-name>/
   # Each step reads its inputs from upstream step folders by convention.
   steps:
     - name: requirements

plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml

@@ -2,7 +2,7 @@ workflow:
   name: docs-workflow
   description: Multi-stage documentation workflow for a JIRA ticket. Requirements analysis, planning, writing, technical review, and style review.
 
-  # All step outputs go to: .claude/docs/<ticket>/<step-name>/
+  # All step outputs go to: .agent_workspace/<ticket>/<step-name>/
   # Each step reads its inputs from upstream step folders by convention.
   steps:
     - name: requirements

plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh

@@ -21,10 +21,11 @@ if ! cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null; then
   exit 2
 fi
 
-MARKER=".claude/docs/.active-workflow"
-
-# No marker → no active workflow → allow stop
-if [ ! -f "$MARKER" ]; then
+# Look for progress files
+shopt -s nullglob
+PROGRESS_FILES=(.agent_workspace/*/workflow/*.json)
+shopt -u nullglob
+if [ ${#PROGRESS_FILES[@]} -eq 0 ]; then
   exit 0
 fi
 

plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md

@@ -160,7 +160,7 @@ No extra fields. Common schema only.
   "completed_at": "2026-04-23T15:00:00Z",
   "topic_count": 8,
   "snippet_count": 42,
-  "repo_path": "/home/user/docs-repo/.claude/docs/proj-123/code-repo/my-project"
+  "repo_path": "/home/user/docs-repo/.agent_workspace/proj-123/code-repo/my-project"
 }
 ```
 

plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py

@@ -8,18 +8,18 @@
 Modes:
 
 1. Explicit source (--repo and/or --pr):
-    python3 resolve_source.py --base-path .claude/docs/proj-123 \
+    python3 resolve_source.py --base-path .agent_workspace/proj-123 \
         --repo https://github.com/org/repo.git --pr https://github.com/org/repo/pull/42
 
 2. From existing source.yaml:
-    python3 resolve_source.py --base-path .claude/docs/proj-123
+    python3 resolve_source.py --base-path .agent_workspace/proj-123
 
 3. JIRA ticket discovery (auto-discover repo from ticket git links):
-    python3 resolve_source.py --base-path .claude/docs/proj-123 \
+    python3 resolve_source.py --base-path .agent_workspace/proj-123 \
         --ticket PROJ-123 --plugin-root /path/to/docs-tools
 
 4. Scan requirements.md for PR URLs (post-requirements discovery):
-    python3 resolve_source.py --base-path .claude/docs/proj-123 --scan-requirements
+    python3 resolve_source.py --base-path .agent_workspace/proj-123 --scan-requirements
 
 Output: JSON to stdout with the resolved source info, or an error status.
 
@@ -793,7 +793,7 @@ def main():
     parser.add_argument(
         "--base-path",
         required=True,
-        help="Base output path (e.g., .claude/docs/proj-123)",
+        help="Base output path (e.g., .agent_workspace/proj-123)",
     )
     parser.add_argument(
         "--repo",

plugins/docs-tools/skills/docs-orchestrator/scripts/setup-hooks.sh

@@ -14,9 +14,9 @@ PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../../.." && pwd)}"
 HOOKS_SRC="${PLUGIN_ROOT}/skills/docs-orchestrator/hooks"
 
 # Copy hook script into the project
-mkdir -p .claude/hooks
-cp "$HOOKS_SRC/workflow-completion-check.sh" .claude/hooks/
-chmod +x .claude/hooks/workflow-completion-check.sh
+mkdir -p .agent_workspace/hooks
+cp "$HOOKS_SRC/workflow-completion-check.sh" .agent_workspace/hooks/
+chmod +x .agent_workspace/hooks/workflow-completion-check.sh
 
 # Create settings file if missing
 if [ ! -f "$SETTINGS_FILE" ]; then
@@ -33,7 +33,7 @@ else
     "matcher": "",
     "hooks": [{
       "type": "command",
-      "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/workflow-completion-check.sh",
+      "command": "bash ${CLAUDE_PROJECT_DIR}/.agent_workspace/hooks/workflow-completion-check.sh",
       "timeout": 10
     }]
   }]' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"