diff --git a/.gitignore b/.gitignore index d3351fcc..a0a03556 100644 --- a/.gitignore +++ b/.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 diff --git a/plugins/docs-tools/README.md b/plugins/docs-tools/README.md index e474a478..f85635be 100644 --- a/plugins/docs-tools/README.md +++ b/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-.yaml` — if `--workflow ` is passed -2. `.claude/docs-workflow.yaml` — project-level default (when no `--workflow` is specified) +1. `.agent_workspace/docs-.yaml` — if `--workflow ` 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 ` 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 ` | Write files to a specific repo path (e.g., an external clone) | | `--create-jira ` | Create a linked JIRA ticket in the specified project | -| `--workflow ` | Use `.claude/docs-.yaml` instead of the default workflow | +| `--workflow ` | Use `.agent_workspace/docs-.yaml` instead of the default workflow | ### Resuming a workflow diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 43269f2e..ddc3b786 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/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: [--workflow ] [--pr ...] [--source-code-repo ...] [--mkdocs] [--draft] [--docs-repo-path ] [--create-jira ] [--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 ` — Use `.claude/docs-.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 ` — Use `.agent_workspace/docs-.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 ...` — 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//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//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 ` — 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 ...` — 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//code-repo//`) 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 ...` — 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//code-repo//`) 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 ` — 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 `/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//source.yaml +# .agent_workspace//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 ` was specified → `.claude/docs-.yaml` -- Otherwise → `.claude/docs-workflow.yaml` +- If `--workflow ` was specified → `.agent_workspace/docs-.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 , (2) re-run with --pr , (3) create .claude/docs//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 , (2) re-run with --pr , (3) create .agent_workspace//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/// +.agent_workspace/// ``` The ticket ID is converted to **lowercase** for directory names (e.g., `PROJ-123` → `proj-123`). @@ -224,7 +224,7 @@ 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. @@ -232,7 +232,7 @@ Use this absolute `BASE_PATH` for the progress file's `base_path` field and for ### Folder structure ``` -.claude/docs/proj-123/ +.agent_workspace/proj-123/ source.yaml (per-ticket source config, if applicable) code-repo/ / (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//` — 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//` — 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//workflow/_.json` +**Location**: `.agent_workspace//workflow/_.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": "", "ticket": "", - "base_path": "/absolute/path/to/.claude/docs/", + "base_path": "/absolute/path/to/.agent_workspace/", "status": "in_progress", "created_at": "", "updated_at": "", @@ -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//workflow/_.json`. +Before starting, check for a progress file at `.agent_workspace//workflow/_.json`. **If a progress file exists:** diff --git a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml index c6954aae..198e22f2 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml +++ b/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/// + # All step outputs go to: .agent_workspace/// # Each step reads its inputs from upstream step folders by convention. steps: - name: requirements diff --git a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-create-jira.yaml b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-create-jira.yaml index 3657d656..6e7b699e 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-create-jira.yaml +++ b/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/// + # All step outputs go to: .agent_workspace/// # Each step reads its inputs from upstream step folders by convention. steps: - name: requirements diff --git a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml index 39104977..bc0f972b 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml +++ b/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/// + # All step outputs go to: .agent_workspace/// # Each step reads its inputs from upstream step folders by convention. steps: - name: requirements diff --git a/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh b/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh index 499db593..e8e4cb25 100755 --- a/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh +++ b/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 diff --git a/plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md b/plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md index 6aeaf2b1..b3d6977d 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md +++ b/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" } ``` diff --git a/plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py b/plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py index 82e0ac10..e1ad3dd0 100755 --- a/plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py +++ b/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", diff --git a/plugins/docs-tools/skills/docs-orchestrator/scripts/setup-hooks.sh b/plugins/docs-tools/skills/docs-orchestrator/scripts/setup-hooks.sh index e974ed9e..cc6f6d46 100755 --- a/plugins/docs-tools/skills/docs-orchestrator/scripts/setup-hooks.sh +++ b/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" diff --git a/plugins/docs-tools/skills/docs-workflow-code-evidence/SKILL.md b/plugins/docs-tools/skills/docs-workflow-code-evidence/SKILL.md index af57f22b..b5c75f15 100644 --- a/plugins/docs-tools/skills/docs-workflow-code-evidence/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-code-evidence/SKILL.md @@ -24,7 +24,7 @@ The writer typically works from the **documentation repository**, not the code r ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--repo ` — Path to the source code repository (required — provided by the orchestrator after clone/verify, or by the user for standalone invocation) - `--scope-include ` — Comma-separated glob patterns to include (e.g., `src/controllers/**,pkg/api/v1/**,README.md`). Scopes both source directory detection and search results. If omitted, the entire repo is in scope. - `--scope-exclude ` — Comma-separated glob patterns to exclude (e.g., `**/vendor/**,**/*_test.go`). Applied as post-retrieval filters since code-finder does not support exclude globs natively. diff --git a/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md b/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md index 267134f1..a97bb2bb 100644 --- a/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md @@ -17,7 +17,7 @@ Unlike other step skills, this skill does **not** dispatch an agent. It runs `sc ## Arguments - `$1` — Parent JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--project ` — Target JIRA project key for the new ticket (required) ## Input diff --git a/plugins/docs-tools/skills/docs-workflow-create-merge-request/SKILL.md b/plugins/docs-tools/skills/docs-workflow-create-merge-request/SKILL.md index 137274db..52705fef 100644 --- a/plugins/docs-tools/skills/docs-workflow-create-merge-request/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-create-merge-request/SKILL.md @@ -15,7 +15,7 @@ Step skill for the docs-orchestrator pipeline. After writing and reviews are com ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--draft` — If present, skip all git operations - `--repo-path ` — Target documentation repository (must already be on a feature branch) diff --git a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md index 9956e9f5..4600b997 100644 --- a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md @@ -12,7 +12,7 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) ## Input diff --git a/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md index 29a04cae..5b4a5ee4 100644 --- a/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md @@ -18,7 +18,7 @@ This skill uses a two-pass architecture to analyze documentation requirements: ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--pr ` — PR/MR URL to include in analysis (repeatable) ## Output diff --git a/plugins/docs-tools/skills/docs-workflow-scope-req-audit/SKILL.md b/plugins/docs-tools/skills/docs-workflow-scope-req-audit/SKILL.md index 8d349d3a..f490c8a7 100644 --- a/plugins/docs-tools/skills/docs-workflow-scope-req-audit/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-scope-req-audit/SKILL.md @@ -18,7 +18,7 @@ This skill classifies each JIRA requirement from the requirements step as ground ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--repo ` — Path to the source code repository (required, provided by orchestrator) - `--grounded-threshold ` — Minimum top score for grounded classification (default: 0.5) - `--absent-threshold ` — Maximum top score for absent classification (default: 0.25) diff --git a/plugins/docs-tools/skills/docs-workflow-start/SKILL.md b/plugins/docs-tools/skills/docs-workflow-start/SKILL.md index 76da8e5f..3c0f7a57 100644 --- a/plugins/docs-tools/skills/docs-workflow-start/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-start/SKILL.md @@ -14,12 +14,12 @@ Interactive entry point for the documentation workflow. Same argument set as docs-orchestrator: - `$1` — JIRA ticket ID (optional at this stage) -- `--workflow ` — Use `.claude/docs-.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 ` — Use `.agent_workspace/docs-.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 ...` — 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//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//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 ` — 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 ...` — 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//code-repo//`) 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, and writing 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 ...` — 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//code-repo//`) 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, and writing 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-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 ## Determine mode @@ -221,7 +221,7 @@ When running individual steps, dependencies are resolved automatically and each ```bash TICKET_LOWER=$(echo "" | tr '[:upper:]' '[:lower:]') -BASE_PATH="$(cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && pwd)/.claude/docs/${TICKET_LOWER}" +BASE_PATH="$(cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && pwd)/.agent_workspace/${TICKET_LOWER}" mkdir -p "$BASE_PATH" ``` @@ -230,10 +230,10 @@ mkdir -p "$BASE_PATH" Determine which workflow YAML to use. If `--workflow ` was provided (from the parsed args), use the named variant; otherwise use the default: ```bash -if [[ -n "$WORKFLOW_NAME" && -f ".claude/docs-${WORKFLOW_NAME}.yaml" ]]; then - YAML_PATH=".claude/docs-${WORKFLOW_NAME}.yaml" -elif [[ -f ".claude/docs-workflow.yaml" ]]; then - YAML_PATH=".claude/docs-workflow.yaml" +if [[ -n "$WORKFLOW_NAME" && -f ".agent_workspace/docs-${WORKFLOW_NAME}.yaml" ]]; then + YAML_PATH=".agent_workspace/docs-${WORKFLOW_NAME}.yaml" +elif [[ -f ".agent_workspace/docs-workflow.yaml" ]]; then + YAML_PATH=".agent_workspace/docs-workflow.yaml" else YAML_PATH="${CLAUDE_PLUGIN_ROOT}/skills/docs-orchestrator/defaults/docs-workflow.yaml" fi @@ -321,9 +321,9 @@ After each step completes: After all steps complete, display a summary: > **Completed steps:** -> - requirements: .claude/docs/proj-123/requirements/ -> - planning: .claude/docs/proj-123/planning/ -> - writing: .claude/docs/proj-123/writing/ +> - requirements: .agent_workspace/proj-123/requirements/ +> - planning: .agent_workspace/proj-123/planning/ +> - writing: .agent_workspace/proj-123/writing/ > > **Skipped steps:** > - code-evidence: no source repository configured diff --git a/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md b/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md index d324b7d4..b314f095 100644 --- a/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md @@ -12,7 +12,7 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--format ` — Documentation format (default: `adoc`) ## Input diff --git a/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md b/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md index a9dd64b6..2f88d749 100644 --- a/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md @@ -16,7 +16,7 @@ This skill performs a single review pass. The iteration loop (re-running with fi ## Arguments - `$1` — JIRA ticket ID (required) -- `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`) - `--repo ` — Path to the source code repository (optional, provided by orchestrator when available) ## Input diff --git a/specs/2026-03-22-docs-workflow-simplification-design.md b/specs/2026-03-22-docs-workflow-simplification-design.md index dd2baac3..942ccd10 100644 --- a/specs/2026-03-22-docs-workflow-simplification-design.md +++ b/specs/2026-03-22-docs-workflow-simplification-design.md @@ -6,7 +6,7 @@ ## Problem -The docs-workflow defaults to writing drafts into a `.claude/docs/` staging area and relies on a convoluted `--integrate` flag with a separate `docs-integrator` agent to place files into the repository. This creates unnecessary friction — most users want docs written directly into the repo. +The docs-workflow defaults to writing drafts into a `.agent_workspace/` staging area and relies on a convoluted `--integrate` flag with a separate `docs-integrator` agent to place files into the repository. This creates unnecessary friction — most users want docs written directly into the repo. ## Decision @@ -27,7 +27,7 @@ Flip the default: the workflow creates a clean branch from the upstream default When `--draft` is passed: - No branch creation — stays on current branch -- Writer saves to `.claude/docs/drafts//` staging area +- Writer saves to `.agent_workspace/drafts//` staging area - Reviewers operate on the staging area - No repo integration @@ -128,7 +128,7 @@ The orchestrator must tell the writer which mode to use: > Place files directly in the repository following existing conventions. Detect the build framework, analyze file naming and directory conventions, and write modules to the correct repo locations. Update navigation/TOC files as needed. **Draft mode prompt addition:** -> Save files to the `.claude/docs/drafts//` staging area. Do not modify any existing repository files. +> Save files to the `.agent_workspace/drafts//` staging area. Do not modify any existing repository files. #### Review stage prompt changes @@ -136,7 +136,7 @@ Stages 4 and 5 must reference files at their actual locations: **Default mode:** Pass the `_index.md` manifest path so reviewers can find all written files. -**Draft mode:** Same as current behavior — hardcoded `.claude/docs/drafts//` paths. +**Draft mode:** Same as current behavior — hardcoded `.agent_workspace/drafts//` paths. #### Usage examples update @@ -167,13 +167,13 @@ Added before the writing guidelines, active only in default (non-draft) mode: #### Output location changes -- **Default mode:** Files written directly to repo locations. The `_index.md` manifest is still created at `.claude/docs/drafts//` as a record of what was written and where. -- **Draft mode (`--draft`):** Files written to `.claude/docs/drafts//` (current behavior, unchanged). +- **Default mode:** Files written directly to repo locations. The `_index.md` manifest is still created at `.agent_workspace/drafts//` as a record of what was written and where. +- **Draft mode (`--draft`):** Files written to `.agent_workspace/drafts//` (current behavior, unchanged). #### Removed - Symlink setup for `_attributes/` etc. (unnecessary when writing directly in repo) -- All language implying `.claude/docs/drafts/` is the *default* output +- All language implying `.agent_workspace/drafts/` is the *default* output ### `plugins/docs-tools/agents/docs-integrator.md` @@ -193,8 +193,8 @@ Added before the writing guidelines, active only in default (non-draft) mode: 2. Fetch JIRA summary → "Add autoscaling support" 3. Auto-detect remote/default branch (origin/main) 4. git checkout -b rhaistrat-123_add-autoscaling-support origin/main -5. Requirements analyst → .claude/docs/requirements/ -6. Docs planner → .claude/docs/plans/ +5. Requirements analyst → .agent_workspace/requirements/ +6. Docs planner → .agent_workspace/plans/ 7. Docs writer: - Detects build framework (e.g., Antora) - Analyzes repo conventions @@ -211,9 +211,9 @@ Added before the writing guidelines, active only in default (non-draft) mode: ``` 1. Parse args, validate JIRA token 2. NO branch creation -3. Requirements analyst → .claude/docs/requirements/ -4. Docs planner → .claude/docs/plans/ -5. Docs writer → .claude/docs/drafts// +3. Requirements analyst → .agent_workspace/requirements/ +4. Docs planner → .agent_workspace/plans/ +5. Docs writer → .agent_workspace/drafts// 6. Technical reviewer → reviews drafts 7. Style reviewer → edits drafts in place 8. (Optional) Create JIRA ticket