@diff-review-system/drs 3.3.1 → 4.0.1

package/README.md

@@ -3,16 +3,17 @@
 [![npm version](https://img.shields.io/npm/v/@diff-review-system/drs)](https://www.npmjs.com/package/@diff-review-system/drs)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-**Automated AI code reviews for GitHub PRs and GitLab MRs.**
+**Workflow-first AI code maintenance for reviews, changelogs, docs, and repository upkeep.**
 
-DRS helps teams catch critical issues earlier with specialized review agents, unified reporting, and CI-friendly automation — all powered by Pi SDK.
+DRS runs agentic workflows for local diffs, GitHub PRs, and GitLab MRs. Review is a first-class packaged workflow, and the same workflow engine can update changelogs, fix review findings, refresh agent guidance, post comments, and compose project-specific maintenance pipelines — all powered by Pi SDK.
 
 ## Why teams like DRS
 
-- 🔒 **Specialized analysis domains**: security, quality, style, performance, documentation
-- 🧠 **Flexible agent pipelines**: compose any review agents (including `unified-reviewer`) in execution order
+- 🧭 **Workflow-first automation**: run packaged or project-defined DAG workflows with `drs workflow run`
+- 🎯 **First-class review workflows**: `local-review`, `github-pr-review`, and `gitlab-mr-review` are included out of the box
+- 🧠 **Flexible agent pipelines**: add your own project-specific `review/*` and `task/*` agents
 - 📦 **Pi-native runtime**: in-process execution by default, no separate runtime service required
-- ✍️ **Description generation**: optional PR/MR summary generation and posting
+- ✍️ **Maintenance workflows**: update changelogs, fix review issues, refresh AGENTS.md-style guidance, and generate PR/MR descriptions
 - 🧾 **Portable outputs**: inline comments, JSON artifacts, and GitLab code quality reports
 - 🎯 **Smart context compression**: dynamic budget sizing with `contextCompression.thresholdPercent`
 
@@ -28,7 +29,7 @@ DRS helps teams catch critical issues earlier with specialized review agents, un
 
 ### 1. Prerequisites
 
-- Node.js 20+
+- Node.js 22.19+
 - API key for your chosen model provider (Anthropic/OpenAI/ZhipuAI/etc.)
 
 ### 2. Install DRS
@@ -49,8 +50,8 @@ drs init
 ### 4. Configure Environment
 
 ```bash
-# Copy example env file
-cp .env.example .env
+# Create a local env file
+touch .env
 
 # Edit .env and set:
 # - GITLAB_TOKEN: Your GitLab access token (for GitLab MRs)
@@ -67,30 +68,63 @@ DRS CLI now loads `.env` automatically from your current working directory.
 
 **Note**: DRS runs Pi in-process by default and does not require a remote runtime endpoint.
 
-### 5. Review Local Changes
+### 5. Run Local Workflows
 
 ```bash
 # Review unstaged changes
-drs review-local
+drs workflow run local-review
 
 # Review staged changes
-drs review-local --staged
+drs workflow run local-review --input staged=true
 
-# Use specific agents
-drs review-local --agents security,quality
+# Update CHANGELOG.md from local changes
+drs workflow run local-changelog-update
+
+# Update CHANGELOG.md from the previous tag to the current tag, or explicit refs
+drs workflow run tag-changelog-update --input from=v3.3.1 --input to=v4.0.0-rc.1
+
+# Fix issues from the latest saved local review artifact
+drs workflow run local-fix-review-issues
+
+# Refresh AGENTS.md or equivalent repository guidance
+drs workflow run local-update-agents-md
+
+# To use project-specific agents, configure review.agents in .drs/drs.config.yaml
+# then run the same workflow.
 ```
 
 ### Most-Used Commands
 
 | Goal | Command |
 |---|---|
-| Review local unstaged changes | `drs review-local` |
-| Review local staged changes | `drs review-local --staged` |
-| Review GitHub PR | `drs review-pr --owner <owner> --repo <repo> --pr <number>` |
-| Review GitLab MR | `drs review-mr --project <group/repo> --mr <number>` |
-| Review by PR/MR URL (auto-detect platform) | `drs review-url <https://.../pull/... or .../-/merge_requests/...>` |
-| Generate PR description | `drs describe-pr --owner <owner> --repo <repo> --pr <number>` |
-| Generate MR description | `drs describe-mr --project <group/repo> --mr <number>` |
+| Review local unstaged changes | `drs workflow run local-review` |
+| Review local staged changes | `drs workflow run local-review --input staged=true` |
+| Update changelog from local changes | `drs workflow run local-changelog-update` |
+| Update changelog from tag range | `drs workflow run tag-changelog-update` |
+| Fix issues from latest saved local review artifact | `drs workflow run local-fix-review-issues` |
+| Update AGENTS.md-style guidance | `drs workflow run local-update-agents-md` |
+| Update changelog and review local changes | `drs workflow run local-changelog-review` |
+| Review GitHub PR via workflow | `drs workflow run github-pr-review --input owner=<owner> --input repo=<repo> --input pr=<number>` |
+| Review GitLab MR via workflow | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number>` |
+| Show GitHub PR review context | `drs workflow run github-pr-show-changes --input owner=<owner> --input repo=<repo> --input pr=<number>` |
+| Show GitLab MR review context | `drs workflow run gitlab-mr-show-changes --input project=<group/repo> --input mr=<number>` |
+| Generate visual PR explainer artifact | `drs workflow run github-pr-visual-explain --input owner=<owner> --input repo=<repo> --input pr=<number>` |
+| Generate visual MR explainer artifact | `drs workflow run gitlab-mr-visual-explain --input project=<group/repo> --input mr=<number>` |
+| Generate visual local diff explainer | `drs workflow run local-visual-explain` |
+| Describe, review, and comment on GitHub PR via workflow | `drs workflow run github-pr-review --input owner=<owner> --input repo=<repo> --input pr=<number> --input describe=true --input post=true` |
+| Describe, review, and comment on GitLab MR via workflow | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number> --input describe=true --input post=true` |
+| Describe, review, comment, and generate visual PR explainer | `drs workflow run github-pr-review --input owner=<owner> --input repo=<repo> --input pr=<number> --input describe=true --input post=true --input visual=true` |
+| Review GitLab MR and write Code Quality report | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number> --input codeQuality=true` |
+| Describe/review/comment GitLab MR and write Code Quality report | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number> --input describe=true --input post=true --input codeQuality=true` |
+| Generate PR description | `drs workflow run github-pr-describe --input owner=<owner> --input repo=<repo> --input pr=<number>` |
+| Generate MR description | `drs workflow run gitlab-mr-describe --input project=<group/repo> --input mr=<number>` |
+| Post or update a PR comment | `drs workflow run github-pr-post-comment --input owner=<owner> --input repo=<repo> --input pr=<number> --input body="..." --input marker=<id>` |
+| Post or update an MR comment | `drs workflow run gitlab-mr-post-comment --input project=<group/repo> --input mr=<number> --input body="..." --input marker=<id>` |
+| Run any configured agent | `drs run-agent task/docs-updater --prompt "Update release notes"` |
+| Run a configured workflow | `drs workflow run release-notes --input-file diff=.drs/diff.md` |
+| Run the default project workflow | `drs workflow run` |
+| List available workflows | `drs workflow list` |
+| Show workflow inputs and steps | `drs workflow show github-pr-review` |
 
 ## Deployment Modes
 
@@ -100,54 +134,46 @@ Review code locally before pushing:
 
 ```bash
 # Review local changes
-drs review-local
+drs workflow run local-review
 
 # Review specific GitLab MR
-drs review-mr --project my-org/my-repo --mr 123 --post-comments
-
-# Review GitLab MR and auto-generate a description (optionally post it)
-drs review-mr --project my-org/my-repo --mr 123 --describe
-drs review-mr --project my-org/my-repo --mr 123 --describe --post-description
-
-# Review GitLab MR and generate code quality report
-drs review-mr --project my-org/my-repo --mr 123 --code-quality-report gl-code-quality-report.json
-
-# Review by PR/MR URL (auto-detect GitHub vs GitLab)
-drs review-url https://github.com/octocat/hello-world/pull/456 --post-comments
-drs review-url https://gitlab.com/my-org/my-repo/-/merge_requests/123 --post-comments
+drs workflow run gitlab-mr-review --input project=my-org/my-repo --input mr=123 --input describe=true --input post=true
 
 # Review specific GitHub PR
-drs review-pr --owner octocat --repo hello-world --pr 456 --post-comments
+drs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456 --input describe=true --input post=true
 
-# Review GitHub PR and auto-generate a description (optionally post it)
-drs review-pr --owner octocat --repo hello-world --pr 456 --describe
-drs review-pr --owner octocat --repo hello-world --pr 456 --describe --post-description
+# Review and generate a visual explainer artifact
+drs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456 --input describe=true --input post=true --input visual=true
 
-# Enable extended thinking for deeper analysis
-drs review-pr --owner octocat --repo hello-world --pr 456 --reasoning-effort high
-drs review-mr --project my-org/my-repo --mr 123 --ultrathink
+# Review local staged changes
+drs workflow run local-review --input staged=true
 
-# Override base branch used for diff hints
-drs review-pr --owner octocat --repo hello-world --pr 456 --base-branch release/2026-01
+# Override model/agent behavior through config, then run workflows
+drs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456
 
-# Generate review JSON first, then post comments after manual review
-drs review-pr --owner octocat --repo hello-world --pr 456 -o review.json
-drs post-comments --input review.json --owner octocat --repo hello-world --pr 456
+# Use ultrathink with workflows
+drs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456 --ultrathink
 
 # Show the diff context passed to agents
-drs show-changes --owner octocat --repo hello-world --pr 456
+drs workflow run github-pr-show-changes --input owner=octocat --input repo=hello-world --input pr=456
 
 # Show diff context for a single file
-drs show-changes --owner octocat --repo hello-world --pr 456 --file src/app.ts
+drs workflow run github-pr-show-changes --input owner=octocat --input repo=hello-world --input pr=456 --input file=src/app.ts
 
-# Show diff context using a specific base branch
-drs show-changes --owner octocat --repo hello-world --pr 456 --base-branch release/2026-01
+# Generate self-contained HTML visual explainers
+drs workflow run local-visual-explain
+drs workflow run github-pr-visual-explain --input owner=octocat --input repo=hello-world --input pr=456
+drs workflow run gitlab-mr-visual-explain --input project=my-org/my-repo --input mr=123
 
 # Generate PR/MR descriptions on demand
-drs describe-pr --owner octocat --repo hello-world --pr 456
-drs describe-pr --owner octocat --repo hello-world --pr 456 --post-description
-drs describe-mr --project my-org/my-repo --mr 123
-drs describe-mr --project my-org/my-repo --mr 123 --post-description
+drs workflow run github-pr-describe --input owner=octocat --input repo=hello-world --input pr=456
+drs workflow run github-pr-describe --input owner=octocat --input repo=hello-world --input pr=456 --input post=true
+drs workflow run gitlab-mr-describe --input project=my-org/my-repo --input mr=123
+drs workflow run gitlab-mr-describe --input project=my-org/my-repo --input mr=123 --input post=true
+
+# Post or update a single marked PR/MR comment
+drs workflow run github-pr-post-comment --input owner=octocat --input repo=hello-world --input pr=456 --input body="Release notes are ready." --input marker=release-notes
+drs workflow run gitlab-mr-post-comment --input project=my-org/my-repo --input mr=123 --input body="Release notes are ready." --input marker=release-notes
 ```
 
 ### Mode 2: GitLab CI/CD
@@ -202,6 +228,51 @@ DRS includes a **secure, pre-configured workflow** at `.github/workflows/pr-revi
 - Maintainer workflow
 - Attack prevention strategies
 
+### Visual PR Explainer Artifacts
+
+DRS includes visual explainer workflows that generate a self-contained HTML page for reviewers:
+
+- `github-pr-visual-explain` writes `.drs/visual-pr-explainer.html` by default.
+- `gitlab-mr-visual-explain` writes `.drs/visual-mr-explainer.html` by default.
+- `local-visual-explain` writes `.drs/visual-local-explainer.html` by default.
+
+The main review workflows also support visual artifacts:
+
+```bash
+drs workflow run github-pr-review \
+  --input owner=octocat \
+  --input repo=hello-world \
+  --input pr=456 \
+  --input describe=true \
+  --input post=true \
+  --input visual=true
+```
+
+The built-in `visual/pr-explainer` agent includes DRS-specific HTML generation guidance out of the box. Override `.drs/agents/visual/pr-explainer/agent.md` or configure `agents.overrides.visual/pr-explainer` to tune the output for your project. If you install an external `visual-explainer` skill, add it through `agents.overrides.visual/pr-explainer.skills` so the agent loads those richer templates and design rules.
+
+To publish the generated page from GitHub Actions, upload it as an artifact:
+
+```yaml
+- name: Generate visual explainer
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    OPENCODE_API_KEY: ${{ secrets.DRS_PROVIDER_API_KEY }}
+  run: |
+    node dist/cli/index.js workflow run github-pr-review \
+      --input owner="${{ github.event.repository.owner.login }}" \
+      --input repo="${{ github.event.repository.name }}" \
+      --input pr="${{ github.event.pull_request.number }}" \
+      --input describe=true \
+      --input post=true \
+      --input visual=true \
+      --input visualOutputPath=".drs/visual-pr-explainer.html"
+
+- uses: actions/upload-artifact@v4
+  with:
+    name: visual-pr-explainer
+    path: .drs/visual-pr-explainer.html
+```
+
 ## GitLab Code Quality Reports
 
 DRS can generate GitLab-compatible code quality reports that integrate seamlessly with GitLab CI/CD. This provides an alternative (or complement) to inline MR comments.
@@ -216,21 +287,19 @@ DRS can generate GitLab-compatible code quality reports that integrate seamlessl
 - **Non-intrusive**: Doesn't create discussion threads
 
 **When to Use:**
-- Use **inline comments** (`--post-comments`) for critical issues requiring discussion
+- Use `describe=true` to update the PR/MR description before review
+- Use `post=true` for review issues requiring discussion
 - Use **code quality reports** (`--code-quality-report`) for comprehensive static analysis
 - Use **both together** for maximum visibility
 
 ### CLI Usage
 
 ```bash
-# Generate code quality report only
-drs review-mr --project my-org/my-repo --mr 123 \
-  --code-quality-report gl-code-quality-report.json
+# Use workflow-based MR review with comments
+drs workflow run gitlab-mr-review --input project=my-org/my-repo --input mr=123 --input describe=true --input post=true
 
-# Use both comments and code quality report
-drs review-mr --project my-org/my-repo --mr 123 \
-  --post-comments \
-  --code-quality-report gl-code-quality-report.json
+# For code quality artifacts, enable codeQuality
+drs workflow run gitlab-mr-review --input project=my-org/my-repo --input mr=123 --input codeQuality=true
 ```
 
 ### GitLab CI Integration
@@ -244,12 +313,7 @@ code_review:
   before_script:
     - npm install -g @diff-review-system/drs
   script:
-    - drs review-mr --project $CI_PROJECT_PATH --mr $CI_MERGE_REQUEST_IID
-        --code-quality-report gl-code-quality-report.json
-  artifacts:
-    reports:
-      codequality: gl-code-quality-report.json
-    expire_in: 1 week
+    - drs workflow run gitlab-mr-review --input project=$CI_PROJECT_PATH --input mr=$CI_MERGE_REQUEST_IID --input describe=true --input post=true
   only:
     - merge_requests
 ```
@@ -295,7 +359,7 @@ DRS runs on Pi SDK as the sole review runtime.
 By default, DRS starts Pi runtime in-process:
 
 ```bash
-drs review-local
+drs workflow run local-review
 ```
 
 ### Runtime Mode
@@ -304,17 +368,13 @@ DRS uses Pi in-process runtime only.
 
 ## Architecture
 
-DRS uses Pi runtime wiring with markdown-based agent definitions:
+DRS uses Pi runtime wiring with markdown-based agent definitions. Agents are addressed by fully qualified ids: `<namespace>/<name>`.
 
 ```
 .pi/
 └── agents/
     └── review/
-        ├── security.md          # Security specialist
-        ├── quality.md           # Code quality expert
-        ├── style.md             # Style checker
-        ├── performance.md       # Performance analyzer
-        └── documentation.md     # Documentation reviewer
+        └── unified-reviewer.md  # Packaged unified reviewer
 ```
 
 Built-in agent definitions live under `.pi/agents`.
@@ -328,15 +388,15 @@ Built-in agent definitions live under `.pi/agents`.
 Create custom agents in your project:
 
 ```bash
-# Create custom security agent
-mkdir -p .drs/agents/security
-cat > .drs/agents/security/agent.md << 'EOF'
+# Override the packaged unified reviewer
+mkdir -p .drs/agents/review/unified-reviewer
+cat > .drs/agents/review/unified-reviewer/agent.md << 'EOF'
 ---
-description: Custom security reviewer
+description: Custom unified reviewer
 model: anthropic/claude-sonnet-4-5-20250929
 ---
 
-You are a security expert for this specific application.
+You are a reviewer for this specific application.
 
 ## Project-Specific Rules
 [Add your custom rules here]
@@ -348,9 +408,9 @@ EOF
 Add project-specific guidance to a built-in agent without replacing its prompt:
 
 ```bash
-mkdir -p .drs/agents/quality
-cat > .drs/agents/quality/context.md << 'EOF'
-# Quality Context
+mkdir -p .drs/agents/review/unified-reviewer
+cat > .drs/agents/review/unified-reviewer/context.md << 'EOF'
+# Unified Reviewer Context
 - Flag functions over 200 lines as HIGH
 - We use TypeORM — flag raw SQL queries
 EOF
@@ -368,11 +428,11 @@ Prioritize correctness, safety, and clarity.
 
 ### Create New Custom Agents
 
-Add agents that don't exist in the built-in set:
+Add review agents that don't exist in the built-in set:
 
 ```bash
-mkdir -p .drs/agents/api-reviewer
-cat > .drs/agents/api-reviewer/agent.md << 'EOF'
+mkdir -p .drs/agents/review/api-reviewer
+cat > .drs/agents/review/api-reviewer/agent.md << 'EOF'
 ---
 description: REST API contract reviewer
 tools:
@@ -383,24 +443,111 @@ Review REST API changes for backward compatibility.
 EOF
 ```
 
-Then add to config: `agents: [security, quality, api-reviewer]`
+Then add to config: `review.agents: [review/unified-reviewer, review/api-reviewer]`
+
+For non-review work, create agents in any namespace and run them directly:
+
+```bash
+mkdir -p .drs/agents/task/docs-updater
+cat > .drs/agents/task/docs-updater/agent.md << 'EOF'
+---
+description: Documentation update assistant
+tools:
+  Read: true
+  Grep: true
+---
+Update documentation based on the user's request.
+EOF
+
+drs run-agent task/docs-updater --prompt "Summarize the latest API changes"
+```
+
+You can also put the run prompt and output behavior in config, then invoke only the agent id:
+
+```yaml
+agents:
+  overrides:
+    task/docs-updater:
+      run:
+        prompt: "Summarize the latest API changes"
+        output: .drs/docs-summary.json
+        json: true
+```
+
+```bash
+drs run task/docs-updater
+```
+
+### Configure Workflows
+
+Workflows compose agents and built-in actions into a dependency graph. They are useful when one agent produces an artifact that another agent or action consumes.
+
+Define reusable project workflows in `.drs/workflows/*.yaml`.
+
+```yaml
+name: release-notes
+inputs:
+  diff:
+    file: .drs/diff.md
+nodes:
+  summarize:
+    agent: task/change-summarizer
+    input: |
+      Summarize these changes:
+
+      {{inputs.diff}}
+    output: summary
+  write-summary:
+    action: write
+    needs: [summarize]
+    input: "{{artifacts.summary}}"
+    writes: RELEASE_NOTES.md
+```
+
+```bash
+drs workflow run release-notes
+drs workflow run # uses workflow.default from .drs/drs.config.yaml when configured
+drs workflow run release-notes --input-file diff=changes.md --json
+```
+
+Select the default workflow in `.drs/drs.config.yaml`:
+
+```yaml
+workflow:
+  default: local-changelog-review
+```
+
+See [docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the full workflow configuration reference.
 
 ### Configure Review Behavior
 
 Edit `.drs/drs.config.yaml`:
 
 ```yaml
+agents:
+  default:
+    model: zhipuai/glm-4.7
+    skills: []
+  namespaces:
+    review:
+      model: anthropic/claude-sonnet-4-5-20250929
+    task:
+      model: openai/gpt-4o
+  overrides:
+    task/docs-updater:
+      run:
+        promptFile: prompts/docs-update.md
+        output: .drs/docs-update.json
+        json: true
+
 review:
   agents:
-    - unified-reviewer
-    - security
-    - quality
+    - review/unified-reviewer
   ignorePatterns:
     - "*.test.ts"
     - "*.md"
   describe:
     enabled: true
-    postDescription: false
   cursorFixLinks:
     enabled: false
     # workspace: my-repo
@@ -419,14 +566,13 @@ describe:
 ```
 
 Notes:
-- `review.describe` controls auto-description when running `review-mr` or `review-pr`.
-- CLI flags override config: `--describe` / `--skip-describe` and `--post-description` / `--skip-post-description`.
-- `review.cursorFixLinks.enabled` adds opt-in `Fix in Cursor` links to posted review comments via Cursor's web deeplink bridge. CLI flags override config: `--fix-in-cursor` / `--skip-fix-in-cursor`.
-- `describe.model` is used by `describe-mr`/`describe-pr` and by review-driven descriptions.
+- Review orchestration is workflow-first in v4: use `drs workflow run ...` for local/PR/MR review.
+- `describe.model` is used by describe workflows and by review-driven descriptions.
 - `contextCompression.thresholdPercent` sets a context-window-aware budget (e.g. `0.15` means 15%).
 - `contextCompression.maxTokens` is the fallback cap when context window metadata is unavailable.
-- `review.agents` explicitly enables deep-review agents; remove an entry to disable that agent.
-- Built-in review agent names are: `unified-reviewer`, `security`, `quality`, `style`, `performance`, `documentation`.
+- `review.agents` controls exactly which review agents run.
+- Packaged built-in review agent ID: `review/unified-reviewer`.
+- Add project-specific review agents under `.drs/agents/review/<name>/agent.md` and include them in `review.agents`.
 - Unknown agent names fail fast with a validation error before review execution starts.
 
 ### Model Pricing Overrides (Cost Reporting)
@@ -504,11 +650,35 @@ contextCompression:
   softBufferTokens: 1500
   hardBufferTokens: 1000
   tokenEstimateDivisor: 4
+  summaryThresholdMultiplier: 3 # use summary-only context above hard limit * multiplier
 ```
 
+### Runtime Timeouts and Provider Retry
+
+To prevent hung reviews, configure runtime-level call/stream timeouts and provider request retry limits:
+
+```yaml
+pi:
+  runtime:
+    operationTimeoutMs: 300000      # timeout for create/prompt/messages calls
+    streamTimeoutMs: 900000         # total timeout while waiting for agent completion
+    streamPollIntervalMs: 2000      # polling cadence for session messages
+  retry:
+    provider:
+      timeoutMs: 45000              # provider request timeout passed to Pi SDK
+      maxRetries: 2                 # provider request retries (Pi SDK)
+      maxRetryDelayMs: 15000        # max backoff delay between retries
+```
+
+Environment variables override runtime timeout fields:
+
+- `DRS_RUNTIME_OPERATION_TIMEOUT_MS`
+- `DRS_RUNTIME_STREAM_TIMEOUT_MS`
+- `DRS_RUNTIME_STREAM_POLL_INTERVAL_MS`
+
 ### Pi-Native Skill Discovery
 
-DRS auto-discovers review skills from these directories when `review.paths.skills` is not set:
+DRS auto-discovers skills from these directories when `agents.paths.skills` is not set:
 
 1. `.drs/skills` (project-level overrides)
 2. `.agents/skills` (legacy/shared project skills)
@@ -528,12 +698,12 @@ Example layout:
   db-indexing/SKILL.md         # Additional Pi-native skill
 ```
 
-To force a single custom skills directory, set `review.paths.skills`:
+To force a single custom skills directory, set `agents.paths.skills`:
 
 ```yaml
-review:
+agents:
   paths:
-    skills: config/review-skills
+    skills: config/agent-skills
 ```
 
 ## Review Domains
@@ -590,7 +760,10 @@ OPENAI_API_KEY=sk-xxx               # For OpenAI models
 
 # Optional
 GITLAB_URL=https://gitlab.com
-REVIEW_AGENTS=security,quality,style,performance
+DRS_DEFAULT_MODEL=anthropic/claude-sonnet-4-5-20250929
+DRS_AGENT_REVIEW_UNIFIED_REVIEWER_MODEL=anthropic/claude-opus-4-5-20251101
+# Configure review agents in .drs/drs.config.yaml via review.agents.
+# Legacy REVIEW_AGENTS is still accepted as a compatibility alias.
 REVIEW_THINKING_LEVEL=medium              # Reasoning effort: off, minimal, low, medium, high, xhigh
 ```
 
@@ -614,13 +787,16 @@ npm run build
 # Run tests
 npm test
 
-# Development mode
-npm run dev
+# Run the CLI from TypeScript once
+npm run dev:cli -- workflow list
+
+# Watch-mode CLI entrypoint
+npm run dev -- workflow list
 ```
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 22.19+
 - API key for your selected provider (Anthropic/OpenAI/ZhipuAI/etc.)
 - GitLab access token (for GitLab MR reviews)
 - GitHub access token (for GitHub PR reviews)
@@ -638,6 +814,7 @@ Apache-2.0
 - [GitHub Actions Integration Guide](docs/GITHUB_ACTIONS_INTEGRATION.md) - GitHub Actions workflow setup
 - [External PR Security Guide](docs/EXTERNAL_PR_SECURITY.md) - Security controls for external contributors
 - [Custom Agents & Skills Guide](docs/CUSTOM_AGENTS.md) - Custom agents, context, skills, and per-agent tools
+- [Workflows Guide](docs/WORKFLOWS.md) - Compose agents and actions into dependency graphs
 - [Model Overrides Guide](docs/MODEL_OVERRIDES.md) - Per-agent model configuration
 - [Pi Documentation](https://github.com/badlogic/pi-mono)
 

package/dist/ci/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/ci/runner.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAgBnD;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAwDjD;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAE9B"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/ci/runner.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAgBnD;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAyDjD;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAE9B"}

package/dist/ci/runner.js

@@ -1,7 +1,7 @@
 import { loadConfig, validateConfig } from '../lib/config.js';
 import { exitProcess } from '../lib/exit.js';
 import { getLogger } from '../lib/logger.js';
-import { reviewMR } from '../cli/review-mr.js';
+import { runWorkflow } from '../cli/workflow.js';
 /**
  * Detect CI environment from environment variables
  */
@@ -56,13 +56,14 @@ export async function runCIReview() {
     log.info(`Project: ${env.projectId} | MR: !${env.mrIid} | Branch: ${env.sourceBranch} → ${env.targetBranch}`);
     // Run review
     try {
-        await reviewMR(config, {
-            projectId: env.projectId,
-            mrIid: env.mrIid,
-            postComments: true, // Always post comments in CI
-            postErrorComment: config.review.postErrorComment ?? false,
-            describe: config.review.describe?.enabled ?? false,
-            postDescription: config.review.describe?.postDescription ?? false,
+        await runWorkflow(config, 'gitlab-mr-review', {
+            inputs: {
+                project: env.projectId,
+                mr: String(env.mrIid),
+                describe: 'true',
+                post: 'true',
+            },
+            workingDir: projectDir,
         });
         log.info('Review complete');
     }

package/dist/ci/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/ci/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/ci/runner.ts"],"names":[],"mappings":"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"}