@martinffx/atelier 1.2.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +22 -24
  3. package/agents/architect.md +1 -1
  4. package/agents/oracle.md +1 -1
  5. package/dist/atelier.js +12 -14
  6. package/package.json +1 -1
  7. package/skills/code-commit/SKILL.md +5 -13
  8. package/skills/code-pull-request/SKILL.md +36 -0
  9. package/skills/code-pull-request/references/common.md +76 -0
  10. package/skills/code-pull-request/references/create-pr.md +122 -0
  11. package/skills/code-pull-request/references/default-template.md +25 -0
  12. package/skills/code-pull-request/references/leave-comment.md +53 -0
  13. package/skills/code-pull-request/references/merge-pr.md +94 -0
  14. package/skills/code-pull-request/references/read-comments.md +61 -0
  15. package/skills/code-pull-request/references/respond-to-comment.md +66 -0
  16. package/skills/code-review/SKILL.md +21 -12
  17. package/skills/code-review/references/reviewers.md +142 -41
  18. package/skills/code-review/references/rq.md +48 -32
  19. package/skills/oracle-debug/SKILL.md +218 -0
  20. package/skills/{code-debug → oracle-debug}/references/bug-patterns.md +3 -3
  21. package/skills/oracle-domain-modelling/SKILL.md +84 -0
  22. package/skills/oracle-grill-me/SKILL.md +20 -0
  23. package/skills/spec-brainstorm/SKILL.md +91 -71
  24. package/skills/spec-finish/SKILL.md +20 -14
  25. package/skills/spec-implement/SKILL.md +3 -2
  26. package/skills/spec-orchestrator/SKILL.md +4 -15
  27. package/skills/spec-plan/SKILL.md +1 -1
  28. package/agents/scout.md +0 -40
  29. package/skills/code-commit/references/pr-workflow.md +0 -145
  30. package/skills/code-debug/SKILL.md +0 -199
  31. package/skills/code-docs/SKILL.md +0 -171
  32. package/skills/code-docs/references/api-docs.md +0 -116
  33. package/skills/code-docs/references/changelog.md +0 -64
  34. package/skills/code-docs/references/readme-structure.md +0 -94
  35. package/skills/oracle-architect/SKILL.md +0 -327
  36. package/skills/oracle-architect/references/api-design.md +0 -345
  37. package/skills/oracle-architect/references/data-modeling.md +0 -318
  38. package/skills/oracle-architect/references/ddd-patterns.md +0 -348
  39. package/skills/oracle-architect/references/interface-design.md +0 -203
  40. package/skills/oracle-challenge/SKILL.md +0 -126
  41. package/skills/oracle-doubt/SKILL.md +0 -252
  42. package/skills/oracle-doubt/references/adversarial-prompt.md +0 -47
  43. package/skills/oracle-grillme/SKILL.md +0 -160
  44. package/skills/oracle-security/SKILL.md +0 -225
  45. package/skills/oracle-security/references/security-patterns.md +0 -236
  46. package/skills/oracle-security/references/threat-modeling-guide.md +0 -137
  47. package/skills/oracle-testing/SKILL.md +0 -237
  48. package/skills/oracle-testing/references/anti-patterns.md +0 -618
  49. package/skills/oracle-testing/references/boundaries.md +0 -579
  50. package/skills/oracle-testing/references/core-testing.md +0 -691
  51. package/skills/oracle-testing/references/edge-testing.md +0 -794
  52. package/skills/oracle-testing/references/stub-driven-tdd.md +0 -322
  53. package/skills/oracle-thinkdeep/SKILL.md +0 -164
  54. /package/skills/{code-debug → oracle-debug}/references/language-tools.md +0 -0
  55. /package/skills/{code-debug → oracle-debug}/references/techniques.md +0 -0
  56. /package/skills/{oracle-grillme → oracle-domain-modelling}/references/ADR-FORMAT.md +0 -0
  57. /package/skills/{oracle-grillme → oracle-domain-modelling}/references/CONTEXT-FORMAT.md +0 -0
@@ -0,0 +1,61 @@
1
+ # Workflow: Read Comments
2
+
3
+ List comments on the current branch's open PR/MR.
4
+
5
+ Start with [common.md](common.md) (platform detection, find the open PR/MR).
6
+
7
+ ---
8
+
9
+ ## Step 1: Find the Open PR/MR
10
+
11
+ Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
12
+ If none is open, stop — nothing to read.
13
+
14
+ ---
15
+
16
+ ## Step 2: List Comments
17
+
18
+ ### GitHub
19
+
20
+ Top-level comments:
21
+
22
+ ```bash
23
+ gh pr view <number> --json comments --jq '.comments[] | {author: .author.login, body: .body, createdAt: .createdAt}'
24
+ ```
25
+
26
+ Inline review comments (file/line threads) — `--json comments` does NOT include
27
+ them, so fetch them separately:
28
+
29
+ ```bash
30
+ gh pr view <number> --json reviewThreads,reviews
31
+ ```
32
+
33
+ Or, for a readable summary of top-level comments:
34
+
35
+ ```bash
36
+ gh pr view <number> --comments
37
+ ```
38
+
39
+ ### GitLab
40
+
41
+ ```bash
42
+ glab mr note list <iid>
43
+ ```
44
+
45
+ This covers both top-level notes and review-thread replies — `glab` has no
46
+ separate `mr discussion` command.
47
+
48
+ ---
49
+
50
+ ## Step 3: Present to the Human
51
+
52
+ Show each comment with:
53
+
54
+ - **Author** (handle)
55
+ - **Body** (full text, or first few lines if long)
56
+ - **Created at** (timestamp)
57
+ - **Type** (top-level note vs. inline review comment, if distinguishable)
58
+ - **File/line** (for inline review comments)
59
+
60
+ Newest first. Group inline review comments by file/line, and threads by their
61
+ parent comment. Don't post anything — this is read-only.
@@ -0,0 +1,66 @@
1
+ # Workflow: Respond to a Comment
2
+
3
+ Post a new comment that references an existing comment on the current branch's PR/MR.
4
+
5
+ This workflow uses **simple reference replies** — a new top-level comment that quotes
6
+ the original — rather than platform-native threaded replies. True threaded replies
7
+ require GraphQL/REST calls and are a possible future enhancement.
8
+
9
+ Start with [common.md](common.md) (platform detection, find the open PR/MR).
10
+
11
+ ---
12
+
13
+ ## Step 1: Find the Open PR/MR and Read Comments
14
+
15
+ Run [common.md](common.md) to find the open PR/MR, then
16
+ [read-comments.md](read-comments.md) to list the comments.
17
+
18
+ ---
19
+
20
+ ## Step 2: Pick the Target Comment
21
+
22
+ Ask the human which comment to respond to. Accept any of:
23
+
24
+ - The comment's number/position in the list above
25
+ - The author's handle
26
+ - A snippet of the comment text
27
+
28
+ Confirm the target before composing the reply.
29
+
30
+ ---
31
+
32
+ ## Step 3: Compose the Reference Reply
33
+
34
+ Ask the human for the response body, then compose a top-level comment in this form:
35
+
36
+ ```
37
+ Re: @<author>'s comment — <quoted snippet>
38
+
39
+ <response body>
40
+ ```
41
+
42
+ Quote only the relevant few words of the original — don't reproduce the entire
43
+ comment. Keep the quote accurate and attributed.
44
+
45
+ ---
46
+
47
+ ## Step 4: Confirm and Post
48
+
49
+ **Show the human the composed reply and the target PR/MR. Ask for confirmation
50
+ before running the write command.**
51
+
52
+ Use the same CLI commands as [leave-comment.md](leave-comment.md#step-3-confirm-and-post)
53
+ to post the reply as a new top-level note.
54
+
55
+ ### GitHub
56
+ ```bash
57
+ gh pr comment <number> --body "<composed reply>"
58
+ ```
59
+
60
+ ### GitLab
61
+ ```bash
62
+ glab mr note <iid> --message "<composed reply>"
63
+ ```
64
+
65
+ After posting, show the human the comment URL or the updated PR/MR URL. Done. Do not
66
+ delete or edit the original comment — this skill create/posts only.
@@ -30,15 +30,25 @@ Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents
30
30
 
31
31
  ## Subagent Architecture
32
32
 
33
+ Use these concrete harness subagent types. If an exact match is unavailable, use the most correct available subagent based on the harness-provided descriptions.
34
+
35
+ | `subagent_type` | Purpose |
36
+ |-----------------|---------|
37
+ | `recon` | Triage only: changed-file analysis, context retrieval, reviewer selection |
38
+ | `oracle` | Parallel reviewer personas, evidence-based critique, failure-mode analysis, challenge validation |
39
+ | `architect` | Architecture, design-boundary, data-model, and API-contract review |
40
+
41
+ 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.
42
+
33
43
  ### rq (Request Review) Subagents
34
44
 
35
- | Step | Subagent | Uses | Parallel | Purpose |
36
- |------|----------|------|----------|---------|
37
- | 1 | Triage | `scout` agent | No | Detect context, select reviewers, identify skills to load |
38
- | 2 | Reviewers | `general` subagent | Yes (per reviewer) | Specialty analysis (loads detected skills) |
39
- | 3 | Synthesis | `general` subagent | No | Deduplicate findings |
40
- | 4 | Architect | `architect` agent | No | Architecture review |
41
- | 5 | Challenge | `oracle` agent | No | Validate findings with sequential-thinking |
45
+ | Step | Parallel | Purpose |
46
+ |------|----------|---------|
47
+ | 1. Triage | No | Detect context, select reviewers, identify relevant skills to look for |
48
+ | 2. Reviewers | Yes (per reviewer) | Specialty analysis using reviewer personas |
49
+ | 3. Synthesis | No | Deduplicate findings inline |
50
+ | 4. Architect | No | Architecture review |
51
+ | 5. Challenge | No | Validate findings with sequential-thinking |
42
52
 
43
53
  ### rs (Respond to Review)
44
54
 
@@ -50,19 +60,18 @@ Follows [code-subagents](../code-subagents/SKILL.md) patterns:
50
60
  - **Parallel dispatch** for independent reviewers
51
61
  - **Sequential dispatch** for dependent steps
52
62
  - **Fresh subagent per task** — no context pollution
53
- - **Skill loading pre-step** before each analysis phase
63
+ - **Relevant skill search pre-step** before each analysis phase
54
64
  - **Error handling**: Log failures, continue with partial results
55
65
 
56
66
  ## Agent Dispatch
57
67
 
58
68
  | Agent | Used In Step |
59
69
  |-------|--------------|
60
- | `scout` | Triage (context retrieval, file analysis) |
70
+ | `recon` | Triage only (context retrieval, file analysis) |
71
+ | `oracle` | Reviewers and challenge validation |
61
72
  | `architect` | Architect (architecture review) |
62
- | `oracle` | Challenge (validate findings, sequential-thinking) |
63
- | `general` | Reviewers, Synthesis |
64
73
 
65
- See [agents/](../agents/) for agent definitions.
74
+ Synthesis is performed inline by the main agent.
66
75
 
67
76
  ## References
68
77
 
@@ -4,13 +4,15 @@
4
4
 
5
5
  All reviewers are dispatched as **parallel subagents** following [code-subagents](../../code-subagents/SKILL.md) patterns.
6
6
 
7
- **Uses:** `general` subagent - One per reviewer, dispatched concurrently
7
+ **Uses:** `oracle` subagent - One per reviewer, dispatched concurrently.
8
+
9
+ 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.
8
10
 
9
11
  ### Task Tool Invocation Template
10
12
 
11
13
  ```yaml
12
14
  # Dispatch ONE subagent per selected reviewer
13
- subagent_type: general
15
+ subagent_type: oracle
14
16
  description: "{ReviewerName} code review"
15
17
  prompt: |
16
18
  You are a {ReviewerName} analyzing code for {focus_area}.
@@ -20,11 +22,13 @@ prompt: |
20
22
  - Framework: {framework}
21
23
  - Files changed: {files}
22
24
 
23
- **PRE-STEP: Load Relevant Skills**
24
- Before reviewing, load these skills:
25
+ **PRE-STEP: Look for Relevant Skills**
26
+ Before reviewing, look for relevant language, framework, testing, architecture, security, or tooling skills.
27
+ Load any relevant skills that are available:
25
28
  {skills_to_load}
26
29
 
27
- Use the `skill` tool to load each skill.
30
+ If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
31
+ Failure to find or load a skill is not a review failure.
28
32
 
29
33
  GIT DIFF:
30
34
  ```diff
@@ -155,7 +159,7 @@ Output findings in this format:
155
159
  - **Pre-existing**: Yes/No
156
160
  ```
157
161
 
158
- Loads: Language-specific skills (`typescript-testing`, `python-testing`, etc.)
162
+ Loads: Look for relevant language-specific skills; load them if available.
159
163
 
160
164
  ---
161
165
 
@@ -186,7 +190,7 @@ Output findings in this format:
186
190
  - **Pre-existing**: Yes/No
187
191
  ```
188
192
 
189
- Loads: Testing skills, language-specific patterns
193
+ Loads: Look for relevant testing and language-specific pattern skills; load them if available.
190
194
 
191
195
  ---
192
196
 
@@ -217,7 +221,102 @@ Output findings in this format:
217
221
  - **Pre-existing**: Yes/No
218
222
  ```
219
223
 
220
- Loads: `oracle-architect`, language architecture skills
224
+ Loads: Look for relevant architecture and language architecture skills; load them if available.
225
+
226
+ ---
227
+
228
+ ## Language Reviewers
229
+
230
+ ### PythonLanguage Reviewer
231
+
232
+ **Prompt Template:**
233
+ ```
234
+ You are a Python Language Reviewer analyzing Python code for language-specific issues.
235
+
236
+ Context:
237
+ - Files: {files}
238
+ - Git diff: {git_diff}
239
+ - Loaded skills: {skills}
240
+
241
+ Focus areas:
242
+ - Type hints, generics, protocols, and runtime/type-checker mismatch
243
+ - Async/sync boundary mistakes and blocking calls in async paths
244
+ - Exception handling, resource cleanup, and context manager usage
245
+ - Packaging, imports, dependency boundaries, and module layout
246
+ - pytest coverage, fixtures, parametrization, and testability
247
+
248
+ Output findings in this format:
249
+ - **Location**: file:line
250
+ - **Severity**: Critical/High/Medium/Low
251
+ - **Issue**: What's wrong
252
+ - **Impact**: What breaks or becomes harder to maintain
253
+ - **Suggestion**: How to fix
254
+ - **Pre-existing**: Yes/No
255
+ ```
256
+
257
+ Loads: Look for relevant Python, framework, testing, architecture, security, or tooling skills; load them if available.
258
+
259
+ ---
260
+
261
+ ### RustLanguage Reviewer
262
+
263
+ **Prompt Template:**
264
+ ```
265
+ You are a Rust Language Reviewer analyzing Rust code for language-specific issues.
266
+
267
+ Context:
268
+ - Files: {files}
269
+ - Git diff: {git_diff}
270
+ - Loaded skills: {skills}
271
+
272
+ Focus areas:
273
+ - Ownership, borrowing, lifetimes, and unnecessary cloning
274
+ - Result/Option handling, error context, and panic/unwrap/expect risk
275
+ - Async, Send/Sync, cancellation, blocking calls, and concurrency safety
276
+ - Trait design, API ergonomics, visibility, and module boundaries
277
+ - Tests, property cases, feature flags, and crate/package conventions
278
+
279
+ Output findings in this format:
280
+ - **Location**: file:line
281
+ - **Severity**: Critical/High/Medium/Low
282
+ - **Issue**: What's wrong
283
+ - **Impact**: What breaks or becomes harder to maintain
284
+ - **Suggestion**: How to fix
285
+ - **Pre-existing**: Yes/No
286
+ ```
287
+
288
+ Loads: Look for relevant Rust, framework, testing, architecture, security, or tooling skills; load them if available.
289
+
290
+ ---
291
+
292
+ ### GoLanguage Reviewer
293
+
294
+ **Prompt Template:**
295
+ ```
296
+ You are a Go Language Reviewer analyzing Go code for language-specific issues.
297
+
298
+ Context:
299
+ - Files: {files}
300
+ - Git diff: {git_diff}
301
+ - Loaded skills: {skills}
302
+
303
+ Focus areas:
304
+ - Error handling, wrapping, sentinel errors, and ignored errors
305
+ - context.Context propagation, cancellation, deadlines, and request scope
306
+ - Goroutine lifecycle, channel safety, data races, and sync primitives
307
+ - Interfaces, package boundaries, exported API shape, and naming conventions
308
+ - Table tests, test helpers, race-sensitive behavior, and module layout
309
+
310
+ Output findings in this format:
311
+ - **Location**: file:line
312
+ - **Severity**: Critical/High/Medium/Low
313
+ - **Issue**: What's wrong
314
+ - **Impact**: What breaks or becomes harder to maintain
315
+ - **Suggestion**: How to fix
316
+ - **Pre-existing**: Yes/No
317
+ ```
318
+
319
+ Loads: Look for relevant Go, framework, testing, architecture, security, or tooling skills; load them if available.
221
320
 
222
321
  ---
223
322
 
@@ -251,7 +350,7 @@ Output findings in this format:
251
350
  - **Pre-existing**: Yes/No
252
351
  ```
253
352
 
254
- Loads: Language-specific lint/style skills
353
+ Loads: Look for relevant language-specific lint/style skills; load them if available.
255
354
 
256
355
  ---
257
356
 
@@ -524,19 +623,19 @@ Output findings in this format:
524
623
 
525
624
  ## Skill Loading Guidelines
526
625
 
527
- Each reviewer should load relevant skills before reviewing:
626
+ 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.
528
627
 
529
- | Reviewer Type | Skills to Load |
530
- |---------------|----------------|
531
- | Correctness | Language-specific (`typescript-testing`, `python-testing`, etc.) |
532
- | Maintainability | Testing skills |
533
- | Architecture | `oracle-architect` |
628
+ | Reviewer Type | Skills to Look For |
629
+ |---------------|--------------------|
630
+ | Correctness | Language-specific and testing skills |
631
+ | Maintainability | Testing, tooling, and language-specific pattern skills |
632
+ | Architecture | Architecture and language architecture skills |
633
+ | Language | Language, framework, testing, architecture, security, and tooling skills |
534
634
  | Pedant | Language-specific lint/style skills |
535
- | Skeptic | None (mindset-based) |
536
- | Archaeologist | None (context-based) |
537
- | Operator | None (experience-based) |
538
- | New Hire | None (fresh-eyes-based) |
539
- | Hybrid | Combine constituent reviewers' skills |
635
+ | Security | Security, framework, and language-specific skills |
636
+ | Performance | Performance, framework, and language-specific skills |
637
+ | Mindset-based personas | Relevant skills if available; otherwise use reviewer prompt |
638
+ | Hybrid | Skills relevant to each constituent reviewer |
540
639
 
541
640
  ---
542
641
 
@@ -553,11 +652,11 @@ Given triage output:
553
652
 
554
653
  ### Dispatch Reviewer Subagents (Parallel)
555
654
 
556
- Each subagent loads its own relevant skills before reviewing:
655
+ Each subagent looks for its own relevant skills before reviewing and loads the available ones:
557
656
 
558
657
  **Security Reviewer:**
559
658
  ```yaml
560
- subagent_type: general
659
+ subagent_type: oracle
561
660
  description: "Security review of PR"
562
661
  prompt: |
563
662
  You are a Security Reviewer analyzing code for security vulnerabilities.
@@ -572,13 +671,13 @@ prompt: |
572
671
  {paste diff here}
573
672
  ```
574
673
 
575
- YOUR FIRST TASK - LOAD SKILLS:
576
- As a Security Reviewer, you should load relevant skills before reviewing:
577
- 1. Load `skill: typescript-testing` (if available) - Use the `skill` tool
674
+ YOUR FIRST TASK - LOOK FOR RELEVANT SKILLS:
675
+ As a Security Reviewer, look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
676
+ Load relevant skills if available, such as `typescript-testing`.
677
+ If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
678
+ Failure to find or load a skill is not a review failure.
578
679
 
579
- This skill contains TypeScript testing guidance that will help you identify issues.
580
-
581
- Focus areas after loading skills:
680
+ Focus areas:
582
681
  - Authentication and authorization flaws
583
682
  - Injection vulnerabilities (SQL, command, XSS)
584
683
  - Secrets in code (API keys, passwords, tokens)
@@ -603,7 +702,7 @@ prompt: |
603
702
 
604
703
  **Correctness Reviewer:**
605
704
  ```yaml
606
- subagent_type: general
705
+ subagent_type: oracle
607
706
  description: "Correctness review of PR"
608
707
  prompt: |
609
708
  You are a Correctness Reviewer analyzing code for logic errors.
@@ -618,13 +717,13 @@ prompt: |
618
717
  {paste diff here}
619
718
  ```
620
719
 
621
- YOUR FIRST TASK - LOAD SKILLS:
622
- As a Correctness Reviewer, you should load relevant skills before reviewing:
623
- 1. Load `skill: typescript-testing` - Use the `skill` tool
624
-
625
- This skill contains TypeScript testing patterns and correctness guidance.
720
+ YOUR FIRST TASK - LOOK FOR RELEVANT SKILLS:
721
+ As a Correctness Reviewer, look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
722
+ Load relevant skills if available, such as `typescript-testing`.
723
+ If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
724
+ Failure to find or load a skill is not a review failure.
626
725
 
627
- Focus areas after loading skills:
726
+ Focus areas:
628
727
  - Logic errors and edge cases
629
728
  - Error handling completeness
630
729
  - Type soundness
@@ -639,7 +738,7 @@ prompt: |
639
738
 
640
739
  **PerformanceOperator Reviewer:**
641
740
  ```yaml
642
- subagent_type: general
741
+ subagent_type: oracle
643
742
  description: "Performance review of PR"
644
743
  prompt: |
645
744
  You are a Performance Operator - performance with production reality.
@@ -654,11 +753,13 @@ prompt: |
654
753
  {paste diff here}
655
754
  ```
656
755
 
657
- YOUR FIRST TASK - LOAD SKILLS:
658
- As a PerformanceOperator Reviewer, you should load relevant skills before reviewing:
659
- 1. Load `skill: typescript-testing` (if available) - Use the `skill` tool
756
+ YOUR FIRST TASK - LOOK FOR RELEVANT SKILLS:
757
+ As a PerformanceOperator Reviewer, look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
758
+ Load relevant skills if available, such as `typescript-testing`.
759
+ If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
760
+ Failure to find or load a skill is not a review failure.
660
761
 
661
- Focus areas after loading skills:
762
+ Focus areas:
662
763
  - Performance issues that matter in prod
663
764
  - N+1 queries at scale
664
765
  - Memory leaks over time
@@ -706,6 +807,6 @@ if not all_findings:
706
807
 
707
808
  1. **Parallel dispatch** — All reviewers run simultaneously
708
809
  2. **Fresh subagent per reviewer** — No context pollution between reviewers
709
- 3. **Self-loading skills** — Each subagent loads its own relevant skills using the `skill` tool
810
+ 3. **Concrete harness agent** — Use `oracle` for reviewer personas; do not use reviewer names or `general` as `subagent_type`
710
811
  4. **Error isolation** — One reviewer failing doesn't block others
711
812
  5. **Structured output** — JSON format for easy aggregation
@@ -4,7 +4,7 @@
4
4
 
5
5
  This workflow:
6
6
  1. Gets diff (git diff against target branch)
7
- 2. Triage Subagent - Analyzes diff, selects reviewers, identifies skills to load
7
+ 2. Triage Subagent - Analyzes diff, selects reviewers, identifies relevant skills to look for
8
8
  3. Reviewer Subagents (parallel) - Each selected reviewer analyzes code
9
9
  4. Synthesis Subagent - Deduplicates findings
10
10
  5. Architect Subagent - Architecture review
@@ -32,14 +32,14 @@ Capture the list of changed files and the full diff.
32
32
 
33
33
  ## Step 2: Triage Subagent
34
34
 
35
- **Purpose:** Analyze diff to determine context, select reviewers, identify skills to load.
35
+ **Purpose:** Analyze diff to determine context, select reviewers, identify relevant skills to look for.
36
36
 
37
- **Uses:** `scout` agent - See [agents/scout.md](../../agents/scout.md)
37
+ **Uses:** `recon` agent.
38
38
 
39
39
  ### Subagent Invocation
40
40
 
41
41
  ```yaml
42
- subagent_type: scout
42
+ subagent_type: recon
43
43
  description: "Triage diff for code review"
44
44
  prompt: |
45
45
  Analyze this code diff to determine review needs.
@@ -56,12 +56,21 @@ prompt: |
56
56
  - Correctness (logic, types, error handling)
57
57
  - Maintainability (naming, complexity, tests)
58
58
  - Architecture (boundaries, layers, SOLID)
59
+ - PythonLanguage (Python language, runtime, typing, packaging, tests)
60
+ - RustLanguage (Rust ownership, lifetimes, errors, async, API design)
61
+ - GoLanguage (Go errors, contexts, concurrency, interfaces, package layout)
59
62
  - SecuritySkeptic (security + failure scenarios)
60
63
  - PerformanceOperator (performance at scale)
61
64
  - MaintainabilityPedant (quality + precision)
62
- 4. **Identify skills to load** based on detected language/framework:
65
+ 4. **Identify relevant skills to look for** based on detected language/framework:
66
+ - Reviewers must look for relevant language, framework, testing, architecture, security, or tooling skills before reviewing.
67
+ - Reviewers should load relevant skills that are available.
68
+ - If no relevant skill is available, reviewers continue with their reviewer prompt.
69
+ - Failure to find or load a skill is not a review failure.
63
70
  - TypeScript → typescript-testing, typescript-fastify (if fastify framework)
64
- - Python → python-testing, python-fastapi (if fastapi framework)
71
+ - Python → python-modern-python, python-testing, python-fastapi (if fastapi framework)
72
+ - Rust → rust-specific skills if available
73
+ - Go → go-specific skills if available
65
74
 
66
75
 
67
76
  Return ONLY valid JSON (no markdown, no code blocks):
@@ -76,6 +85,8 @@ prompt: |
76
85
  }
77
86
  ```
78
87
 
88
+ `skills_to_load` lists best-effort skill candidates for reviewers to look for and load if available. It does not make any skill mandatory.
89
+
79
90
  ### Expected Output
80
91
 
81
92
  ```json
@@ -92,23 +103,27 @@ prompt: |
92
103
 
93
104
  **Purpose:** Each selected reviewer analyzes the code from their specialty perspective.
94
105
 
95
- **Uses:** `general` subagent - One per reviewer, dispatched concurrently
106
+ **Uses:** `oracle` agent - One per reviewer, dispatched concurrently.
107
+
108
+ Reviewer names are prompt personas, not subagent types. Do not use `general`, `Security`, `Correctness`, `PerformanceOperator`, or any other reviewer name as `subagent_type`.
96
109
 
97
110
  **Pattern:** Spawn one subagent per reviewer **concurrently** (parallel execution).
98
111
 
99
- ### Skill Loading Pre-Step
112
+ ### Relevant Skill Search Pre-Step
100
113
 
101
- Before dispatching reviewers, the detected skills are passed to each reviewer:
114
+ Before dispatching reviewers, the detected relevant skills are passed to each reviewer as best-effort guidance:
102
115
  ```json
103
116
  {
104
117
  "skills_to_load": ["typescript-testing"]
105
118
  }
106
119
  ```
107
120
 
121
+ The `skills_to_load` field name is retained for compatibility. Treat it as optional guidance: reviewers must look for relevant skills, load the available ones, and continue if none are available.
122
+
108
123
  ### Subagent Invocation (One per Reviewer)
109
124
 
110
125
  ```yaml
111
- subagent_type: general
126
+ subagent_type: oracle
112
127
  description: "Security review of code diff"
113
128
  prompt: |
114
129
  You are a Security Reviewer analyzing code for security vulnerabilities.
@@ -118,11 +133,13 @@ prompt: |
118
133
  - Framework: {framework}
119
134
  - Files: {files}
120
135
 
121
- **PRE-STEP: Load Relevant Skills**
122
- Before reviewing, load these skills:
136
+ **PRE-STEP: Look for Relevant Skills**
137
+ Before reviewing, look for relevant language, framework, testing, architecture, security, or tooling skills.
138
+ Load any relevant skills that are available:
123
139
  {skills_to_load}
124
140
 
125
- Use the `skill` tool to load each skill.
141
+ If no relevant skill is available or a skill cannot be loaded, continue with this reviewer prompt.
142
+ Failure to find or load a skill is not a review failure.
126
143
 
127
144
  DIFF:
128
145
  {git_diff}
@@ -184,18 +201,13 @@ for reviewer in reviewers:
184
201
 
185
202
  ---
186
203
 
187
- ## Step 4: Synthesis Subagent (First Pass)
204
+ ## Step 4: Synthesis First Pass
188
205
 
189
206
  **Purpose:** Group, deduplicate, and assign initial severity.
190
207
 
191
- **Uses:** `general` subagent
208
+ **Uses:** Inline synthesis by the main agent.
192
209
 
193
- ### Subagent Invocation
194
-
195
- ```yaml
196
- subagent_type: general
197
- description: "Synthesize code review findings"
198
- prompt: |
210
+ ```markdown
199
211
  Synthesize these code review findings from multiple reviewers.
200
212
 
201
213
  RAW FINDINGS:
@@ -231,7 +243,7 @@ prompt: |
231
243
 
232
244
  **Purpose:** Review architecture-specific concerns.
233
245
 
234
- **Uses:** `architect` agent - See [agents/architect.md](../../agents/architect.md)
246
+ **Uses:** `architect` agent.
235
247
 
236
248
  ### Subagent Invocation
237
249
 
@@ -249,9 +261,11 @@ prompt: |
249
261
  SYNTHESIZED FINDINGS:
250
262
  {synthesized_findings_json}
251
263
 
252
- **PRE-STEP: Load Relevant Skills**
253
- Before reviewing, load:
254
- - Use `skill` tool to load: oracle-architect
264
+ **PRE-STEP: Look for Relevant Skills**
265
+ Before reviewing, look for relevant architecture and language architecture skills.
266
+ Load relevant skills if available, such as `typescript-api-design` or the language skill for this codebase.
267
+ If no relevant skill is available or a skill cannot be loaded, continue with this architect prompt.
268
+ Failure to find or load a skill is not a review failure.
255
269
 
256
270
  Focus areas:
257
271
  - Boundary violations
@@ -284,7 +298,7 @@ prompt: |
284
298
 
285
299
  **Purpose:** Validate findings by challenging assumptions.
286
300
 
287
- **Uses:** `oracle` agent - See [agents/oracle.md](../../agents/oracle.md)
301
+ **Uses:** `oracle` agent.
288
302
 
289
303
  ### Subagent Invocation
290
304
 
@@ -297,9 +311,11 @@ prompt: |
297
311
  ALL FINDINGS (includes synthesized + architecture):
298
312
  {all_findings_json}
299
313
 
300
- **PRE-STEP: Load Relevant Skills**
301
- Before challenging, load:
302
- - Use `skill` tool to load: oracle-challenge
314
+ **PRE-STEP: Look for Relevant Skills**
315
+ Before challenging, look for relevant language, framework, or debugging skills.
316
+ Load relevant skills if available, such as a language-specific testing skill.
317
+ If no relevant skill is available or a skill cannot be loaded, continue with this challenge prompt.
318
+ Failure to find or load a skill is not a review failure.
303
319
 
304
320
  For each flagged finding, use `mcp__sequential-thinking__sequentialthinking` to analyze:
305
321
  1. Is this handled elsewhere in the codebase?
@@ -348,9 +364,9 @@ Display findings in terminal per [output.md](./output.md).
348
364
  | Step | Subagent | Uses | Parallel? | Purpose |
349
365
  |------|----------|------|----------|---------|
350
366
  | 1 | Get Diff | inline | — | `git diff <branch>` |
351
- | 2 | Triage | `scout` agent | No | Detect context, select reviewers, identify skills |
352
- | 3 | Reviewers | `general` subagent | Yes (per reviewer) | Specialty analysis |
353
- | 4 | Synthesis | `general` subagent | No | Deduplicate and group |
367
+ | 2 | Triage | `recon` agent | No | Detect context, select reviewers, identify relevant skills to look for |
368
+ | 3 | Reviewers | `oracle` agent | Yes (per reviewer) | Specialty analysis |
369
+ | 4 | Synthesis | inline | No | Deduplicate and group |
354
370
  | 5 | Architect | `architect` agent | No | Architecture review |
355
371
  | 6 | Challenge | `oracle` agent | No | Validate findings |
356
372
  | 7 | Output | inline | — | Format and display findings |