Add ambient compatibility

.ambient/ambient.json

@@ -0,0 +1,19 @@
+{
+  "name": "Docs Pipeline (Headless)",
+  "description": "Scheduled, headless documentation pipeline. Scrapes JIRA for tickets labeled 'ambient-docs-ready', runs each through the docs workflow (requirements, planning, writing, technical review, style review), and outputs to the filesystem for human review.",
+  "systemPrompt": "You are a headless documentation pipeline on ACP. Execute the batch-controller skill immediately. No user interaction — make all decisions autonomously. If a ticket fails, log the error and continue to the next.\n\nStandard file locations:\n- Config: .ambient/ambient.json\n- Skills: .claude/skills/*/SKILL.md\n- ACP guidelines: adapters/ambient/CLAUDE.md\n- Workflow config: .claude/docs-acp.yaml\n- Repo mapping: adapters/ambient/repo-mapping.yaml\n- Scripts: adapters/ambient/scripts/\n- Output: artifacts/\n\nTool selection:\n- Use Read for: known paths, JSON files, skill files, config files\n- Use Glob for: discovery, finding multiple files by pattern\n- Use Grep for: content-based searches across files\n- Never glob for standard files — read them directly by path\n\nFile path tracking: Remember paths you wrote to and reuse them with Read. Do not re-discover with Glob.",
+  "startupPrompt": "Execute the batch-controller skill. Do not greet the user or wait for input. Begin processing immediately.",
+  "results": {
+    "Requirements": "artifacts/*/requirements/requirements.md",
+    "Plans": "artifacts/*/planning/plan.md",
+    "Writing Manifests": "artifacts/*/writing/_index.md",
+    "AsciiDoc Drafts": "artifacts/*/writing/**/*.adoc",
+    "MkDocs Drafts": "artifacts/*/writing/**/*.md",
+    "Technical Reviews": "artifacts/*/technical-review/review.md",
+    "Style Reviews": "artifacts/*/style-review/review.md",
+    "Repo Info": "artifacts/*/repo-info.json",
+    "Publish Info": "artifacts/*/publish-info.json",
+    "Batch Summary": "artifacts/batch-summary.md",
+    "Workflow State": "artifacts/*/workflow/*.json"
+  }
+}

.claude/agents/docs-planner.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/agents/docs-planner.md

.claude/agents/docs-reviewer.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/agents/docs-reviewer.md

.claude/agents/docs-writer.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/agents/docs-writer.md

.claude/agents/requirements-analyst.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/agents/requirements-analyst.md

.claude/agents/technical-reviewer.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/agents/technical-reviewer.md

.claude/docs-acp.yaml

@@ -0,0 +1,27 @@
+# ACP headless variant — 5 steps (no prepare-branch or create-jira).
+# Repo setup and publishing are handled externally by batch-controller scripts.
+# For the full interactive workflow, see: plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml
+# Invoked via: --workflow acp
+workflow:
+  name: docs-acp
+  description: Headless documentation pipeline for scheduled ACP sessions.
+  steps:
+    - name: requirements
+      skill: docs-workflow-requirements
+      description: Analyze documentation requirements from JIRA ticket
+    - name: planning
+      skill: docs-workflow-planning
+      description: Create documentation plan with JTBD framework
+      inputs: [requirements]
+    - name: writing
+      skill: docs-workflow-writing
+      description: Write complete documentation modules
+      inputs: [planning]
+    - name: technical-review
+      skill: docs-workflow-tech-review
+      description: Technical accuracy review
+      inputs: [writing]
+    - name: style-review
+      skill: docs-workflow-style-review
+      description: Style guide compliance review
+      inputs: [writing]

.claude/reference/asciidoc-reference.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/reference/asciidoc-reference.md

.claude/reference/checklist.md

@@ -0,0 +1 @@
+../../plugins/cqa-tools/reference/checklist.md

.claude/reference/comparison-guide.md

@@ -0,0 +1 @@
+../../plugins/jtbd-tools/reference/comparison-guide.md

.claude/reference/consolidation-guide.md

@@ -0,0 +1 @@
+../../plugins/jtbd-tools/reference/consolidation-guide.md

.claude/reference/dita-rewrite-fixing-instructions.md

@@ -0,0 +1 @@
+../../plugins/dita-tools/reference/dita-rewrite-fixing-instructions.md

.claude/reference/example-toc.md

@@ -0,0 +1 @@
+../../plugins/jtbd-tools/reference/example-toc.md

.claude/reference/jtbd-docs-plan-template.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/reference/jtbd-docs-plan-template.md

.claude/reference/jtbd-framework.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/reference/jtbd-framework.md

.claude/reference/methodology.md

@@ -0,0 +1 @@
+../../plugins/jtbd-tools/reference/methodology.md

.claude/reference/mkdocs-reference.md

@@ -0,0 +1 @@
+../../plugins/docs-tools/reference/mkdocs-reference.md

.claude/reference/schema.md

@@ -0,0 +1 @@
+../../plugins/jtbd-tools/reference/schema.md

.claude/reference/scoring-guide.md

@@ -0,0 +1 @@
+../../plugins/cqa-tools/reference/scoring-guide.md

.claude/reference/toc-guidelines.md

@@ -0,0 +1 @@
+../../plugins/jtbd-tools/reference/toc-guidelines.md

.claude/skills/article-extractor

@@ -0,0 +1 @@
+../../plugins/docs-tools/skills/article-extractor

.claude/skills/batch-controller/SKILL.md

@@ -0,0 +1,196 @@
+# Batch Controller
+
+Autonomous batch processor for the Ambient Code Platform. Scrapes JIRA for labeled tickets and runs each through the documentation pipeline.
+
+See [reference.md](reference.md) for JSON schemas, MR/PR creation details, config variables, and batch summary format.
+
+## Step 0: Environment setup
+
+Read the ACP guidelines, then run setup:
+
+```
+Read adapters/ambient/CLAUDE.md
+```
+
+If the file cannot be read, STOP and report the error.
+
+```bash
+bash adapters/ambient/setup.sh
+source ~/.env 2>/dev/null
+export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel)/.claude}"
+```
+
+If setup fails, run `batch-progress.sh abort` and stop the session.
+
+## Step 1: Discover tickets
+
+```bash
+TICKETS_JSON="$(bash adapters/ambient/scripts/batch-find-tickets.sh \
+  ${DOCS_JIRA_PROJECT:+--jira-project "$DOCS_JIRA_PROJECT"})"
+```
+
+This script queries JIRA for both `ambient-docs-ready` and `ambient-docs-processing` labels, then cross-references `batch-progress.json` to filter out already-completed tickets. It returns JSON with four lists: `ready`, `orphaned`, `skipped`, and `all`.
+
+If `all` is empty, write a batch summary, run `batch-progress.sh finish`, and end the session.
+
+## Step 1.5: Claim tickets
+
+For tickets in the `ready` list, swap labels to prevent double-processing:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-writer/scripts/jira_writer.py \
+  --issue <TICKET> \
+  --labels-remove ambient-docs-ready \
+  --labels-add ambient-docs-processing
+```
+
+Skip the label swap for tickets in the `orphaned` list — they already have `ambient-docs-processing` from a previous session that crashed or was interrupted.
+
+Run per-ticket for error isolation. If a claim fails, skip that ticket. This step must complete for all tickets before processing begins.
+
+After claiming, register all tickets (from the `all` list) with the progress tracker:
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh init <TICKET-1> <TICKET-2> ...
+```
+
+## Batch progress tracking
+
+`setup.sh` creates `artifacts/batch-progress.json` with `status: "in_progress"` at boot. The stop hook **blocks Claude from stopping** until the batch is explicitly finished. Call `batch-progress.sh` at each pipeline transition:
+
+| Command | When |
+|---------|------|
+| `init <tickets...>` | After claiming tickets (Step 1.5) |
+| `step <N>` | At each sub-step (2a–2f) |
+| `ticket-done` | After a ticket succeeds |
+| `ticket-failed` | After a ticket fails |
+| `finish` | After writing batch summary (Step 3) |
+| `abort` | Fatal error — end session early |
+
+## Step 2: Process each ticket
+
+For each claimed ticket, run steps 2a–2g sequentially.
+
+**Working directory:** Steps 2c and 2d run git/gh commands in the cloned target repo, which may change your working directory. Before every `batch-progress.sh` call, ensure you are in the agent-tools repo root:
+
+```bash
+cd "${REPO_ROOT}"
+```
+
+Verify this resolves to the agent-tools repo (contains `adapters/ambient/`), not a cloned docs repo under `.work/`.
+
+### 2a. Resolve and clone target repo
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh step 2a
+bash adapters/ambient/scripts/repo-setup.sh <TICKET-KEY>
+```
+
+Read `artifacts/<ticket>/repo-info.json` for `format`, `repo_url`, `clone_path`, and `platform`.
+
+### 2b. Invoke the orchestrator
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh step 2b
+```
+
+Resolve orchestrator flags from `repo-info.json`:
+
+```bash
+REPO_FLAGS="$(bash adapters/ambient/scripts/resolve-repo-context.sh "<TICKET-KEY>")"
+```
+
+Then invoke the orchestrator with the resolved flags:
+
+```
+Skill: docs-orchestrator, args: "<TICKET-KEY> --workflow acp ${REPO_FLAGS}"
+```
+
+### 2c. Publish changes
+
+```bash
+cd "${REPO_ROOT}"
+bash adapters/ambient/scripts/batch-progress.sh step 2c
+```
+
+Only if `repo_url` is non-null in `repo-info.json`:
+
+```bash
+bash adapters/ambient/scripts/repo-publish.sh <TICKET-KEY>
+```
+
+Return to the agent-tools repo root after publishing (the script operates in the cloned repo):
+
+```bash
+cd "${REPO_ROOT}"
+```
+
+### 2d. Create or update MR/PR
+
+```bash
+cd "${REPO_ROOT}"
+bash adapters/ambient/scripts/batch-progress.sh step 2d
+```
+
+Only if `publish-info.json` has `pushed: true`:
+
+```bash
+bash adapters/ambient/scripts/repo-create-mr.sh <TICKET-KEY>
+```
+
+Read `artifacts/<ticket>/mr-info.json` for the MR/PR URL. Record it for the batch summary. If the script fails, log the error and continue — the branch is already pushed.
+
+Return to the agent-tools repo root:
+
+```bash
+cd "${REPO_ROOT}"
+```
+
+### 2e. Record the result
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh step 2e
+```
+
+Track ticket key, status, MR/PR URL (if created), and any error messages.
+
+### 2f. Update JIRA labels
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh step 2f
+```
+
+On success: `--labels-remove ambient-docs-processing --labels-add ambient-docs-generated`
+On failure: `--labels-remove ambient-docs-processing --labels-add ambient-docs-failed`
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-writer/scripts/jira_writer.py \
+  --issue <TICKET> --labels-remove ambient-docs-processing --labels-add <LABEL>
+```
+
+If the label update fails, log the error and continue.
+
+### 2g. Continue to the next ticket
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh ticket-done   # or ticket-failed
+```
+
+Do not stop between tickets.
+
+## Step 3: Write batch summary
+
+Write `artifacts/batch-summary.md` (see [reference.md](reference.md) for format), then release the stop hook:
+
+```bash
+bash adapters/ambient/scripts/batch-progress.sh finish
+```
+
+## Error handling
+
+- **JIRA access fails** (Step 1): Write error summary, run `batch-progress.sh abort`, stop.
+- **Label claim fails** (Step 1.5): Skip that ticket — another session likely claimed it.
+- **Single ticket fails** (Step 2): Log error, update label to failed, continue to next ticket.
+- **Label update fails** (Step 2f): Log warning, continue.
+- **Session dies mid-processing**: Tickets retain `ambient-docs-processing`. The next batch session will detect these as orphaned via `batch-find-tickets.sh` and resume processing automatically.
+- **No tickets found**: Write summary noting zero tickets, run `batch-progress.sh finish`, end session.

.claude/skills/batch-controller/reference.md

@@ -0,0 +1,92 @@
+# Batch Controller Reference
+
+## repo-info.json schema
+
+Written by `repo-setup.sh` to `artifacts/<ticket>/repo-info.json`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ticket` | string | Original ticket key (e.g., `VROOM-123`) |
+| `jira_project` | string | Extracted project key (e.g., `VROOM`) |
+| `repo_url` | string\|null | Target repo URL, or null if no mapping / clone failed |
+| `clone_path` | string | Absolute path to local clone (under `.work/`) |
+| `branch` | string | Feature branch name (lowercase ticket key) |
+| `platform` | string | `github` or `gitlab` |
+| `default_branch` | string | Target branch for MR/PR (usually `main`) |
+| `format` | string | `mkdocs` or `adoc` |
+
+## publish-info.json schema
+
+Written by `repo-publish.sh` to `artifacts/<ticket>/publish-info.json`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `branch` | string | Feature branch name |
+| `commit_sha` | string\|null | Commit SHA if committed, null if skipped |
+| `files_committed` | string[] | List of committed file paths (relative to repo root) |
+| `platform` | string | `github` or `gitlab` |
+| `repo_url` | string | Target repo URL |
+| `pushed` | boolean | Whether the branch was pushed to remote |
+| `skip_reason` | string | Present only if `pushed` is false |
+
+## Step 2d: MR/PR creation details
+
+> **Note:** MR/PR creation is now handled by `adapters/ambient/scripts/repo-create-mr.sh`. The details below are retained for reference and debugging.
+
+Read `artifacts/<ticket>/publish-info.json`. Only proceed if `pushed` is `true`.
+
+First, check if an MR/PR already exists for the source branch. Re-runs force-push to the same branch, which automatically updates any open MR/PR.
+
+**For GitLab** (`platform` = `gitlab`):
+
+Use the GitLab API with `GITLAB_TOKEN` from `~/.env`. Extract the project path from `repo_url` (URL-encode it for the API).
+
+1. Check for existing MR: `GET /api/v4/projects/<encoded_path>/merge_requests?source_branch=<branch>&state=opened`
+2. If an open MR exists: record its URL
+3. If no open MR: create via `POST /api/v4/projects/<encoded_path>/merge_requests` with `source_branch`, `target_branch` (from default_branch), `title: "docs(<ticket>): <summary>"`, `description` listing committed files and JIRA link
+
+**For GitHub** (`platform` = `github`):
+
+Use `gh` CLI (authenticates via `GITHUB_TOKEN`):
+
+1. Check: `gh pr list --head "<branch>" --repo "<owner/repo>" --json url`
+2. If exists: record URL
+3. If not: `gh pr create --repo "<owner/repo>" --head "<branch>" --base "<default_branch>" --title "docs(<ticket>): <summary>" --body "<description>"`
+
+Record the MR/PR URL in the batch summary. If creation fails, log and continue — the branch is already pushed.
+
+## Configuration
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `DOCS_TRIGGER_LABEL` | Label marking tickets for processing | `ambient-docs-ready` |
+| `DOCS_PROCESSING_LABEL` | Label added when ticket is claimed | `ambient-docs-processing` |
+| `DOCS_DONE_LABEL` | Label added after success | `ambient-docs-generated` |
+| `DOCS_FAILED_LABEL` | Label added after failure | `ambient-docs-failed` |
+| `DOCS_JIRA_PROJECT` | Limit to specific JIRA project | — |
+
+## Batch summary format
+
+Write to `artifacts/batch-summary.md`:
+
+```markdown
+# Batch Summary
+
+**Date**: YYYY-MM-DD HH:MM UTC
+**Tickets processed**: N
+**Successful**: X
+**Failed**: Y
+
+## Results
+
+| Ticket | Status | Output Path | MR/PR | Notes |
+|--------|--------|-------------|-------|-------|
+| PROJ-123 | success | artifacts/proj-123/ | <url> | 5 modules written |
+| PROJ-456 | failed | — | — | Error: ... |
+
+## Errors
+
+### PROJ-456
+
+<error details>
+```

.claude/skills/cqa-assess

@@ -0,0 +1 @@
+../../plugins/cqa-tools/skills/cqa-assess