@martinffx/atelier 1.2.1 → 1.3.0

package/skills/code-pull-request/references/merge-pr.md

@@ -0,0 +1,94 @@
+# Workflow: Merge PR/MR
+
+Merge the current branch's open PR/MR after confirming CI is green.
+
+Defaults: **squash merge + delete the source branch**. If CI is pending, abort and
+report — don't block waiting unless the human says otherwise.
+
+Start with [common.md](common.md) (platform detection, base branch, preflight).
+
+---
+
+## Step 1: Find or Create the Open PR/MR
+
+Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
+
+- **Open** → continue to Step 2.
+- **None** → run [create-pr.md](create-pr.md) first, then continue.
+- **Closed/merged** → check for new commits since it was closed
+  (`git log --oneline origin/<base>..HEAD`); stop if none.
+
+---
+
+## Step 2: Check CI Is Green
+
+### GitHub
+```bash
+gh pr checks <number>            # all checks
+gh pr checks <number> --required # the merge gate
+```
+Exit codes for `--required`: 0 = all required checks pass; non-zero includes the
+pending case (exit 8). Use `gh pr checks <number> --watch` to wait if the human
+asks for it.
+
+`--required` only shows required checks. If the full run shows failing **optional**
+checks (lint, coverage, etc.), warn the human before proceeding — don't silently
+ignore them.
+
+### GitLab
+```bash
+glab ci status
+# or
+glab pipeline status
+```
+
+If any required check is **pending**, offer auto-merge instead of a direct merge:
+`gh pr merge --auto` (GitHub) or `glab mr merge --auto-merge` (GitLab) queues the
+merge to run once checks pass. A bare `gh pr merge` fails while required checks
+are pending — "merge anyway" does not work in that state. Note: `glab mr merge`
+enables auto-merge by default while a pipeline is running.
+
+If any required check is **failing**, stop and report the status to the human.
+Don't merge on red. If the human says "merge anyway": on GitHub a forced merge
+requires `--admin` (bypasses branch protection, needs admin rights on the repo) —
+state that implication explicitly before using it. On GitLab, merging on red is
+controlled by project settings — ask the human to fix the pipeline or adjust the
+setting.
+
+---
+
+## Step 3: Confirm Before Merging
+
+**Show the human:**
+- PR/MR URL and number/iid
+- CI status (green/red)
+- Merge strategy (squash by default)
+- Whether the source branch will be deleted
+
+Ask for explicit confirmation before running the merge command.
+
+---
+
+## Step 4: Merge
+
+### GitHub
+```bash
+gh pr merge <number> --squash --delete-branch
+```
+Alternatives: `--rebase`, `--merge`, `--auto` (merge automatically once required
+checks pass), or `--admin` (forced merge — see Step 2) per the human's request.
+
+### GitLab
+```bash
+glab mr merge <iid> --squash --remove-source-branch
+```
+Alternatives: `--rebase`, or `--auto-merge` (merge once the pipeline succeeds —
+already the default while a pipeline is running) per the human's request.
+
+---
+
+## Step 5: Report
+
+Show the human the merge result — the merge commit SHA, the target branch tip, and
+whether the source branch was deleted. Suggest switching back to the base branch
+locally (`git checkout <base> && git pull`) if the source branch was removed. Done.

package/skills/code-pull-request/references/read-comments.md

@@ -0,0 +1,61 @@
+# Workflow: Read Comments
+
+List comments on the current branch's open PR/MR.
+
+Start with [common.md](common.md) (platform detection, find the open PR/MR).
+
+---
+
+## Step 1: Find the Open PR/MR
+
+Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
+If none is open, stop — nothing to read.
+
+---
+
+## Step 2: List Comments
+
+### GitHub
+
+Top-level comments:
+
+```bash
+gh pr view <number> --json comments --jq '.comments[] | {author: .author.login, body: .body, createdAt: .createdAt}'
+```
+
+Inline review comments (file/line threads) — `--json comments` does NOT include
+them, so fetch them separately:
+
+```bash
+gh pr view <number> --json reviewThreads,reviews
+```
+
+Or, for a readable summary of top-level comments:
+
+```bash
+gh pr view <number> --comments
+```
+
+### GitLab
+
+```bash
+glab mr note list <iid>
+```
+
+This covers both top-level notes and review-thread replies — `glab` has no
+separate `mr discussion` command.
+
+---
+
+## Step 3: Present to the Human
+
+Show each comment with:
+
+- **Author** (handle)
+- **Body** (full text, or first few lines if long)
+- **Created at** (timestamp)
+- **Type** (top-level note vs. inline review comment, if distinguishable)
+- **File/line** (for inline review comments)
+
+Newest first. Group inline review comments by file/line, and threads by their
+parent comment. Don't post anything — this is read-only.

package/skills/code-pull-request/references/respond-to-comment.md

@@ -0,0 +1,66 @@
+# Workflow: Respond to a Comment
+
+Post a new comment that references an existing comment on the current branch's PR/MR.
+
+This workflow uses **simple reference replies** — a new top-level comment that quotes
+the original — rather than platform-native threaded replies. True threaded replies
+require GraphQL/REST calls and are a possible future enhancement.
+
+Start with [common.md](common.md) (platform detection, find the open PR/MR).
+
+---
+
+## Step 1: Find the Open PR/MR and Read Comments
+
+Run [common.md](common.md) to find the open PR/MR, then
+[read-comments.md](read-comments.md) to list the comments.
+
+---
+
+## Step 2: Pick the Target Comment
+
+Ask the human which comment to respond to. Accept any of:
+
+- The comment's number/position in the list above
+- The author's handle
+- A snippet of the comment text
+
+Confirm the target before composing the reply.
+
+---
+
+## Step 3: Compose the Reference Reply
+
+Ask the human for the response body, then compose a top-level comment in this form:
+
+```
+Re: @<author>'s comment — <quoted snippet>
+
+<response body>
+```
+
+Quote only the relevant few words of the original — don't reproduce the entire
+comment. Keep the quote accurate and attributed.
+
+---
+
+## Step 4: Confirm and Post
+
+**Show the human the composed reply and the target PR/MR. Ask for confirmation
+before running the write command.**
+
+Use the same CLI commands as [leave-comment.md](leave-comment.md#step-3-confirm-and-post)
+to post the reply as a new top-level note.
+
+### GitHub
+```bash
+gh pr comment <number> --body "<composed reply>"
+```
+
+### GitLab
+```bash
+glab mr note <iid> --message "<composed reply>"
+```
+
+After posting, show the human the comment URL or the updated PR/MR URL. Done. Do not
+delete or edit the original comment — this skill create/posts only.

package/skills/code-review/SKILL.md

@@ -30,15 +30,25 @@ Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents
 
 ## Subagent Architecture
 
+Use these concrete harness subagent types. If an exact match is unavailable, use the most correct available subagent based on the harness-provided descriptions.
+
+| `subagent_type` | Purpose |
+|-----------------|---------|
+| `recon` | Triage only: changed-file analysis, context retrieval, reviewer selection |
+| `oracle` | Parallel reviewer personas, evidence-based critique, failure-mode analysis, challenge validation |
+| `architect` | Architecture, design-boundary, data-model, and API-contract review |
+
+Reviewer names such as `Security`, `Correctness`, `Maintainability`, and `PerformanceOperator` are prompt personas, not subagent types. Do not use `general`; it is not a harness agent.
+
 ### rq (Request Review) Subagents
 
-| Step | Subagent | Uses | Parallel | Purpose |
-|------|----------|------|----------|---------|
-| 1 | Triage | `scout` agent | No | Detect context, select reviewers, identify skills to load |
-| 2 | Reviewers | `general` subagent | Yes (per reviewer) | Specialty analysis (loads detected skills) |
-| 3 | Synthesis | `general` subagent | No | Deduplicate findings |
-| 4 | Architect | `architect` agent | No | Architecture review |
-| 5 | Challenge | `oracle` agent | No | Validate findings with sequential-thinking |
+| Step | Parallel | Purpose |
+|------|----------|---------|
+| 1. Triage | No | Detect context, select reviewers, identify relevant skills to look for |
+| 2. Reviewers | Yes (per reviewer) | Specialty analysis using reviewer personas |
+| 3. Synthesis | No | Deduplicate findings inline |
+| 4. Architect | No | Architecture review |
+| 5. Challenge | No | Validate findings with sequential-thinking |
 
 ### rs (Respond to Review)
 
@@ -50,19 +60,18 @@ Follows [code-subagents](../code-subagents/SKILL.md) patterns:
 - **Parallel dispatch** for independent reviewers
 - **Sequential dispatch** for dependent steps
 - **Fresh subagent per task** — no context pollution
-- **Skill loading pre-step** before each analysis phase
+- **Relevant skill search pre-step** before each analysis phase
 - **Error handling**: Log failures, continue with partial results
 
 ## Agent Dispatch
 
 | Agent | Used In Step |
 |-------|--------------|
-| `scout` | Triage (context retrieval, file analysis) |
+| `recon` | Triage only (context retrieval, file analysis) |
+| `oracle` | Reviewers and challenge validation |
 | `architect` | Architect (architecture review) |
-| `oracle` | Challenge (validate findings, sequential-thinking) |
-| `general` | Reviewers, Synthesis |
 
-See [agents/](../agents/) for agent definitions.
+Synthesis is performed inline by the main agent.
 
 ## References
 

package/skills/code-review/references/reviewers.md

@@ -4,13 +4,15 @@
 
 All reviewers are dispatched as **parallel subagents** following [code-subagents](../../code-subagents/SKILL.md) patterns.
 
-**Uses:** `general` subagent - One per reviewer, dispatched concurrently
+**Uses:** `oracle` subagent - One per reviewer, dispatched concurrently.
+
+Reviewer names such as `Security`, `Correctness`, `Maintainability`, and `PerformanceOperator` are personas inside the prompt. They are not subagent types. Do not use `general`; it is not a harness agent.
 
 ### Task Tool Invocation Template
 
 ```yaml
 # Dispatch ONE subagent per selected reviewer
-subagent_type: general
+subagent_type: oracle
 description: "{ReviewerName} code review"
 prompt: |
   You are a {ReviewerName} analyzing code for {focus_area}.
@@ -20,11 +22,13 @@ prompt: |
   - Framework: {framework}
   - Files changed: {files}
 
-  **PRE-STEP: Load Relevant Skills**
-  Before reviewing, load these skills:
+  **PRE-STEP: Look for Relevant Skills**
+  Before reviewing, look for relevant language, framework, testing, architecture, security, or tooling skills.
+  Load any relevant skills that are available:
   {skills_to_load}
 
-  Use the `skill` tool to load each skill.
+  If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
+  Failure to find or load a skill is not a review failure.
 
   GIT DIFF:
   ```diff
@@ -155,7 +159,7 @@ Output findings in this format:
 - **Pre-existing**: Yes/No
 ```
 
-Loads: Language-specific skills (`typescript-testing`, `python-testing`, etc.)
+Loads: Look for relevant language-specific skills; load them if available.
 
 ---
 
@@ -186,7 +190,7 @@ Output findings in this format:
 - **Pre-existing**: Yes/No
 ```
 
-Loads: Testing skills, language-specific patterns
+Loads: Look for relevant testing and language-specific pattern skills; load them if available.
 
 ---
 
@@ -217,7 +221,102 @@ Output findings in this format:
 - **Pre-existing**: Yes/No
 ```
 
-Loads: `oracle-architect`, language architecture skills
+Loads: Look for relevant architecture and language architecture skills; load them if available.
+
+---
+
+## Language Reviewers
+
+### PythonLanguage Reviewer
+
+**Prompt Template:**
+```
+You are a Python Language Reviewer analyzing Python code for language-specific issues.
+
+Context:
+- Files: {files}
+- Git diff: {git_diff}
+- Loaded skills: {skills}
+
+Focus areas:
+- Type hints, generics, protocols, and runtime/type-checker mismatch
+- Async/sync boundary mistakes and blocking calls in async paths
+- Exception handling, resource cleanup, and context manager usage
+- Packaging, imports, dependency boundaries, and module layout
+- pytest coverage, fixtures, parametrization, and testability
+
+Output findings in this format:
+- **Location**: file:line
+- **Severity**: Critical/High/Medium/Low
+- **Issue**: What's wrong
+- **Impact**: What breaks or becomes harder to maintain
+- **Suggestion**: How to fix
+- **Pre-existing**: Yes/No
+```
+
+Loads: Look for relevant Python, framework, testing, architecture, security, or tooling skills; load them if available.
+
+---
+
+### RustLanguage Reviewer
+
+**Prompt Template:**
+```
+You are a Rust Language Reviewer analyzing Rust code for language-specific issues.
+
+Context:
+- Files: {files}
+- Git diff: {git_diff}
+- Loaded skills: {skills}
+
+Focus areas:
+- Ownership, borrowing, lifetimes, and unnecessary cloning
+- Result/Option handling, error context, and panic/unwrap/expect risk
+- Async, Send/Sync, cancellation, blocking calls, and concurrency safety
+- Trait design, API ergonomics, visibility, and module boundaries
+- Tests, property cases, feature flags, and crate/package conventions
+
+Output findings in this format:
+- **Location**: file:line
+- **Severity**: Critical/High/Medium/Low
+- **Issue**: What's wrong
+- **Impact**: What breaks or becomes harder to maintain
+- **Suggestion**: How to fix
+- **Pre-existing**: Yes/No
+```
+
+Loads: Look for relevant Rust, framework, testing, architecture, security, or tooling skills; load them if available.
+
+---
+
+### GoLanguage Reviewer
+
+**Prompt Template:**
+```
+You are a Go Language Reviewer analyzing Go code for language-specific issues.
+
+Context:
+- Files: {files}
+- Git diff: {git_diff}
+- Loaded skills: {skills}
+
+Focus areas:
+- Error handling, wrapping, sentinel errors, and ignored errors
+- context.Context propagation, cancellation, deadlines, and request scope
+- Goroutine lifecycle, channel safety, data races, and sync primitives
+- Interfaces, package boundaries, exported API shape, and naming conventions
+- Table tests, test helpers, race-sensitive behavior, and module layout
+
+Output findings in this format:
+- **Location**: file:line
+- **Severity**: Critical/High/Medium/Low
+- **Issue**: What's wrong
+- **Impact**: What breaks or becomes harder to maintain
+- **Suggestion**: How to fix
+- **Pre-existing**: Yes/No
+```
+
+Loads: Look for relevant Go, framework, testing, architecture, security, or tooling skills; load them if available.
 
 ---
 
@@ -251,7 +350,7 @@ Output findings in this format:
 - **Pre-existing**: Yes/No
 ```
 
-Loads: Language-specific lint/style skills
+Loads: Look for relevant language-specific lint/style skills; load them if available.
 
 ---
 
@@ -524,19 +623,19 @@ Output findings in this format:
 
 ## Skill Loading Guidelines
 
-Each reviewer should load relevant skills before reviewing:
+Each reviewer must look for relevant skills before reviewing. Load relevant skills if available; otherwise continue with the reviewer prompt. Failure to find or load a skill is not a review failure.
 
-| Reviewer Type | Skills to Load |
-|---------------|----------------|
-| Correctness | Language-specific (`typescript-testing`, `python-testing`, etc.) |
-| Maintainability | Testing skills |
-| Architecture | `oracle-architect` |
+| Reviewer Type | Skills to Look For |
+|---------------|--------------------|
+| Correctness | Language-specific and testing skills |
+| Maintainability | Testing, tooling, and language-specific pattern skills |
+| Architecture | Architecture and language architecture skills |
+| Language | Language, framework, testing, architecture, security, and tooling skills |
 | Pedant | Language-specific lint/style skills |
-| Skeptic | None (mindset-based) |
-| Archaeologist | None (context-based) |
-| Operator | None (experience-based) |
-| New Hire | None (fresh-eyes-based) |
-| Hybrid | Combine constituent reviewers' skills |
+| Security | Security, framework, and language-specific skills |
+| Performance | Performance, framework, and language-specific skills |
+| Mindset-based personas | Relevant skills if available; otherwise use reviewer prompt |
+| Hybrid | Skills relevant to each constituent reviewer |
 
 ---
 
@@ -553,11 +652,11 @@ Given triage output:
 
 ### Dispatch Reviewer Subagents (Parallel)
 
-Each subagent loads its own relevant skills before reviewing:
+Each subagent looks for its own relevant skills before reviewing and loads the available ones:
 
 **Security Reviewer:**
 ```yaml
-subagent_type: general
+subagent_type: oracle
 description: "Security review of PR"
 prompt: |
   You are a Security Reviewer analyzing code for security vulnerabilities.
@@ -572,13 +671,13 @@ prompt: |
   {paste diff here}
   ```
 
-  YOUR FIRST TASK - LOAD SKILLS:
-  As a Security Reviewer, you should load relevant skills before reviewing:
-  1. Load `skill: typescript-testing` (if available) - Use the `skill` tool
+  YOUR FIRST TASK - LOOK FOR RELEVANT SKILLS:
+  As a Security Reviewer, look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
+  Load relevant skills if available, such as `typescript-testing`.
+  If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
+  Failure to find or load a skill is not a review failure.
 
-  This skill contains TypeScript testing guidance that will help you identify issues.
-
-  Focus areas after loading skills:
+  Focus areas:
   - Authentication and authorization flaws
   - Injection vulnerabilities (SQL, command, XSS)
   - Secrets in code (API keys, passwords, tokens)
@@ -603,7 +702,7 @@ prompt: |
 
 **Correctness Reviewer:**
 ```yaml
-subagent_type: general
+subagent_type: oracle
 description: "Correctness review of PR"
 prompt: |
   You are a Correctness Reviewer analyzing code for logic errors.
@@ -618,13 +717,13 @@ prompt: |
   {paste diff here}
   ```
 
-  YOUR FIRST TASK - LOAD SKILLS:
-  As a Correctness Reviewer, you should load relevant skills before reviewing:
-  1. Load `skill: typescript-testing` - Use the `skill` tool
-
-  This skill contains TypeScript testing patterns and correctness guidance.
+  YOUR FIRST TASK - LOOK FOR RELEVANT SKILLS:
+  As a Correctness Reviewer, look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
+  Load relevant skills if available, such as `typescript-testing`.
+  If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
+  Failure to find or load a skill is not a review failure.
 
-  Focus areas after loading skills:
+  Focus areas:
   - Logic errors and edge cases
   - Error handling completeness
   - Type soundness
@@ -639,7 +738,7 @@ prompt: |
 
 **PerformanceOperator Reviewer:**
 ```yaml
-subagent_type: general
+subagent_type: oracle
 description: "Performance review of PR"
 prompt: |
   You are a Performance Operator - performance with production reality.
@@ -654,11 +753,13 @@ prompt: |
   {paste diff here}
   ```
 
-  YOUR FIRST TASK - LOAD SKILLS:
-  As a PerformanceOperator Reviewer, you should load relevant skills before reviewing:
-  1. Load `skill: typescript-testing` (if available) - Use the `skill` tool
+  YOUR FIRST TASK - LOOK FOR RELEVANT SKILLS:
+  As a PerformanceOperator Reviewer, look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
+  Load relevant skills if available, such as `typescript-testing`.
+  If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
+  Failure to find or load a skill is not a review failure.
 
-  Focus areas after loading skills:
+  Focus areas:
   - Performance issues that matter in prod
   - N+1 queries at scale
   - Memory leaks over time
@@ -706,6 +807,6 @@ if not all_findings:
 
 1. **Parallel dispatch** — All reviewers run simultaneously
 2. **Fresh subagent per reviewer** — No context pollution between reviewers
-3. **Self-loading skills** — Each subagent loads its own relevant skills using the `skill` tool
+3. **Concrete harness agent** — Use `oracle` for reviewer personas; do not use reviewer names or `general` as `subagent_type`
 4. **Error isolation** — One reviewer failing doesn't block others
 5. **Structured output** — JSON format for easy aggregation