Safe discussions, pull request reviews and better errors

.github/workflows/test-claude-create-pull-request-review-comment.md

@@ -0,0 +1,29 @@
+---
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  reaction: eyes
+
+engine: 
+  id: claude
+
+if: contains(github.event.pull_request.title, 'prr')
+
+safe-outputs:
+  create-pull-request-review-comment:
+    max: 3
+---
+
+Analyze the pull request and create a few targeted review comments on the code changes. 
+
+Create 2-3 review comments focusing on:
+1. Code quality and best practices
+2. Potential security issues or improvements  
+3. Performance optimizations or concerns
+
+For each review comment, specify:
+- The exact file path where the comment should be placed
+- The specific line number in the diff
+- A helpful comment body with actionable feedback
+
+If you find multi-line issues, use start_line to comment on ranges of lines.

.github/workflows/test-codex-create-pull-request-review-comment.md

@@ -0,0 +1,29 @@
+---
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  reaction: eyes
+
+engine: 
+  id: codex
+
+if: contains(github.event.pull_request.title, 'prr')
+
+safe-outputs:
+  create-pull-request-review-comment:
+    max: 3
+---
+
+Analyze the pull request and create a few targeted review comments on the code changes.
+
+Create 2-3 review comments focusing on:
+1. Code quality and best practices
+2. Potential security issues or improvements
+3. Performance optimizations or concerns
+
+For each review comment, specify:
+- The exact file path where the comment should be placed
+- The specific line number in the diff
+- A helpful comment body with actionable feedback
+
+If you find multi-line issues, use start_line to comment on ranges of lines.

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "parser": "typescript",
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "bracketSpacing": true,
+  "arrowParens": "avoid"
+}

Makefile

@@ -99,6 +99,11 @@ validate-workflows:
 fmt:
 	go fmt ./...
 
+# Format JavaScript (.cjs) files
+.PHONY: fmt-cjs
+fmt-cjs:
+	npm run format:cjs
+
 # Run TypeScript compiler on JavaScript files
 .PHONY: js
 js:
@@ -113,9 +118,19 @@ fmt-check:
 		exit 1; \
 	fi
 
+# Check JavaScript (.cjs) file formatting
+.PHONY: fmt-check-cjs
+fmt-check-cjs:
+	npm run lint:cjs
+
+# Lint JavaScript (.cjs) files 
+.PHONY: lint-cjs
+lint-cjs: fmt-check-cjs
+	@echo "✓ JavaScript formatting validated"
+
 # Validate all project files
 .PHONY: lint
-lint: fmt-check golint
+lint: fmt-check lint-cjs golint
 	@echo "✓ All validations passed"
 
 # Install the binary locally
@@ -205,7 +220,7 @@ copy-copilot-to-claude:
 
 # Agent should run this task before finishing its turns
 .PHONY: agent-finish
-agent-finish: deps-dev fmt lint js build test-all recompile
+agent-finish: deps-dev fmt fmt-cjs lint js build test-all recompile
 	@echo "Agent finished tasks successfully."
 
 # Help target
@@ -222,7 +237,10 @@ help:
 	@echo "  deps             - Install dependencies"
 	@echo "  lint             - Run linter"
 	@echo "  fmt              - Format code"
+	@echo "  fmt-cjs          - Format JavaScript (.cjs) files"
 	@echo "  fmt-check        - Check code formatting"
+	@echo "  fmt-check-cjs    - Check JavaScript (.cjs) file formatting"
+	@echo "  lint-cjs         - Lint JavaScript (.cjs) files"
 	@echo "  validate-workflows - Validate compiled workflow lock files"
 	@echo "  validate         - Run all validations (fmt-check, lint, validate-workflows)"
 	@echo "  install          - Install binary locally"

docs/safe-outputs.md

@@ -27,10 +27,11 @@ For example:
 ```yaml
 safe-outputs:
   create-issue:
+  create-discussion:
   add-issue-comment:
 ```
 
-This declares that the workflow should create at most one new issue and add at most one comment to the triggering issue or pull request based on the agentic workflow's output. To create multiple issues or comments, use the `max` parameter.
+This declares that the workflow should create at most one new issue, at most one new discussion, and add at most one comment to the triggering issue or pull request based on the agentic workflow's output. To create multiple issues, discussions, or comments, use the `max` parameter.
 
 ## Available Output Types
 
@@ -66,6 +67,40 @@ Create new issues with your findings. For each issue, provide a title starting w
 
 The compiled workflow will have additional prompting describing that, to create issues, it should write the issue details to a file.
 
+### New Discussion Creation (`create-discussion:`)
+
+Adding discussion creation to the `safe-outputs:` section declares that the workflow should conclude with the creation of GitHub discussions based on the workflow's output.
+
+**Basic Configuration:**
+```yaml
+safe-outputs:
+  create-discussion:
+```
+
+**With Configuration:**
+```yaml
+safe-outputs:
+  create-discussion:
+    title-prefix: "[ai] "            # Optional: prefix for discussion titles
+    category-id: "DIC_kwDOGFsHUM4BsUn3"  # Optional: specific discussion category ID
+    max: 3                           # Optional: maximum number of discussions (default: 1)
+```
+
+The agentic part of your workflow should describe the discussion(s) it wants created.
+
+**Example markdown to generate the output:**
+
+```yaml
+# Research Discussion Agent
+
+Research the latest developments in AI and create discussions to share findings.
+Create new discussions with your research findings. For each discussion, provide a title starting with "AI Research Update" and detailed summary of the findings.
+```
+
+The compiled workflow will have additional prompting describing that, to create discussions, it should write the discussion details to a file.
+
+**Note:** If no `category-id` is specified, the workflow will use the first available discussion category in the repository.
+
 ### Issue Comment Creation (`add-issue-comment:`)
 
 Adding comment creation to the `safe-outputs:` section declares that the workflow should conclude with posting comments based on the workflow's output. By default, comments are posted on the triggering issue or pull request, but this can be configured using the `target` option.
@@ -135,6 +170,54 @@ Analyze the latest commit and suggest improvements.
 2. Create a pull request for your improvements, with a descriptive title and detailed description of the changes made
 ```
 
+### Pull Request Review Comment Creation (`create-pull-request-review-comment:`)
+
+Adding `create-pull-request-review-comment:` to the `safe-outputs:` section declares that the workflow should conclude with creating review comments on specific lines of code in the current pull request based on the workflow's output.
+
+**Basic Configuration:**
+```yaml
+safe-outputs:
+  create-pull-request-review-comment:
+```
+
+**With Configuration:**
+```yaml
+safe-outputs:
+  create-pull-request-review-comment:
+    max: 3                          # Optional: maximum number of review comments (default: 1)
+    side: "RIGHT"                   # Optional: side of the diff ("LEFT" or "RIGHT", default: "RIGHT")
+```
+
+The agentic part of your workflow should describe the review comment(s) it wants created with specific file paths and line numbers.
+
+**Example natural language to generate the output:**
+
+```markdown
+# Code Review Agent
+
+Analyze the pull request changes and provide line-specific feedback.
+Create review comments on the pull request with your analysis findings. For each comment, specify:
+- The file path
+- The line number (required)
+- The start line number (optional, for multi-line comments)
+- The comment body with specific feedback
+
+Review comments can target single lines or ranges of lines in the diff.
+```
+
+The compiled workflow will have additional prompting describing that, to create review comments, it should write the comment details to a special file with the following structure:
+- `path`: The file path relative to the repository root
+- `line`: The line number where the comment should be placed
+- `start_line`: (Optional) The starting line number for multi-line comments
+- `side`: (Optional) The side of the diff ("LEFT" for old version, "RIGHT" for new version)
+- `body`: The comment content
+
+**Key Features:**
+- Only works in pull request contexts for security
+- Supports both single-line and multi-line code comments
+- Comments are automatically positioned on the correct side of the diff
+- Maximum comment limits prevent spam
+
 ### Label Addition (`add-issue-label:`)
 
 Adding `add-issue-label:` to the `safe-outputs:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the coding agent's analysis.

package.json

@@ -8,6 +8,7 @@
     "@types/node": "^24.3.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
+    "prettier": "^3.4.2",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
@@ -16,7 +17,9 @@
     "test": "npm run typecheck && vitest run",
     "test:js": "vitest run",
     "test:js-watch": "vitest",
-    "test:js-coverage": "vitest run --coverage"
+    "test:js-coverage": "vitest run --coverage",
+    "format:cjs": "prettier --write 'pkg/workflow/js/**/*.cjs'",
+    "lint:cjs": "prettier --check 'pkg/workflow/js/**/*.cjs'"
   },
   "dependencies": {
     "vite": "^7.1.4"

pkg/cli/templates/instructions.md

@@ -114,6 +114,14 @@ The YAML frontmatter supports these fields:
         draft: true                     # Optional: create as draft PR (defaults to true)
     ```
     When using `output.create-pull-request`, the main job does **not** need `contents: write` or `pull-requests: write` permissions since PR creation is handled by a separate job with appropriate permissions.
+  - `create-pull-request-review-comment:` - Safe PR review comment creation on code lines
+    ```yaml
+    safe-outputs:
+      create-pull-request-review-comment:
+        max: 3                          # Optional: maximum number of review comments (default: 1)
+        side: "RIGHT"                   # Optional: side of diff ("LEFT" or "RIGHT", default: "RIGHT")
+    ```
+    When using `safe-outputs.create-pull-request-review-comment`, the main job does **not** need `pull-requests: write` permission since review comment creation is handled by a separate job with appropriate permissions.
   - `update-issue:` - Safe issue updates 
     ```yaml
     safe-outputs: