my-opencode 1.0.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.
- package/LICENSE +21 -0
- package/README.md +163 -0
- package/agents/architect.md +30 -0
- package/agents/code-reviewer.md +29 -0
- package/agents/executor.md +30 -0
- package/agents/fullstack-dev.md +53 -0
- package/agents/spec-writer.md +37 -0
- package/agents/team-lead.md +60 -0
- package/agents/tech-writer.md +30 -0
- package/agents/test-engineer.md +30 -0
- package/agents/verifier.md +33 -0
- package/bin/cli.js +272 -0
- package/opencode.json +164 -0
- package/package.json +44 -0
- package/skills/adr/SKILL.md +91 -0
- package/skills/adr/references/templates.md +100 -0
- package/skills/adr/scripts/README.md +5 -0
- package/skills/dev-flow/SKILL.md +188 -0
- package/skills/dev-flow/references/code-phase.md +72 -0
- package/skills/dev-flow/references/contract-phase.md +81 -0
- package/skills/dev-flow/references/verify-phase.md +129 -0
- package/skills/dev-flow/scripts/README.md +3 -0
- package/skills/docs-gen/SKILL.md +162 -0
- package/skills/docs-gen/references/doc-styles.md +216 -0
- package/skills/docs-gen/scripts/README.md +5 -0
- package/skills/orchestrate/SKILL.md +112 -0
- package/skills/orchestrate/references/orchestration-patterns.md +56 -0
- package/skills/pr-review/SKILL.md +110 -0
- package/skills/pr-review/references/review-dimensions.md +117 -0
- package/skills/pr-review/references/security-checklist.md +122 -0
- package/skills/pr-review/scripts/README.md +5 -0
- package/skills/test-gen/SKILL.md +143 -0
- package/skills/test-gen/references/framework-detection.md +105 -0
- package/skills/test-gen/references/test-patterns.md +260 -0
- package/skills/test-gen/scripts/README.md +5 -0
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# Doc Style Reference — Language-Specific Conventions
|
|
2
|
+
|
|
3
|
+
## TypeScript / JavaScript — JSDoc
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
/**
|
|
7
|
+
* Creates a new user in the system.
|
|
8
|
+
*
|
|
9
|
+
* @param name - The user's display name (2-50 chars)
|
|
10
|
+
* @param email - The user's email address (must be unique)
|
|
11
|
+
* @returns The created user object with generated ID
|
|
12
|
+
* @throws {ValidationError} If name or email are invalid
|
|
13
|
+
* @throws {ConflictError} If email already exists
|
|
14
|
+
*/
|
|
15
|
+
async function createUser(name: string, email: string): Promise<User> {
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### JSDoc Tags
|
|
19
|
+
| Tag | When to Use |
|
|
20
|
+
|-----|-------------|
|
|
21
|
+
| `@param name - desc` | Every function parameter |
|
|
22
|
+
| `@returns` | Non-void functions |
|
|
23
|
+
| `@throws` | Documented exceptions |
|
|
24
|
+
| `@template T` | Generic type parameters |
|
|
25
|
+
| `@deprecated reason` | Deprecated APIs, with migration path |
|
|
26
|
+
| `@example` | Usage example (preferred over prose) |
|
|
27
|
+
| `@see` | Cross-reference to related code |
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## TypeScript / JavaScript — TSDoc
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
/**
|
|
35
|
+
* Creates a new user in the system.
|
|
36
|
+
*
|
|
37
|
+
* @param name - The user's display name (2-50 chars)
|
|
38
|
+
* @param email - The user's email address (must be unique)
|
|
39
|
+
* @returns The created user
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* ```ts
|
|
43
|
+
* const user = await createUser('Alice', 'alice@test.com')
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
TSDoc is a superset of JSDoc with better TypeScript integration. Prefer TSDoc in TypeScript projects.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Python — Google Style Docstrings
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
def create_user(name: str, email: str) -> User:
|
|
56
|
+
"""Create a new user in the system.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
name: The user's display name (2-50 chars).
|
|
60
|
+
email: The user's email address (must be unique).
|
|
61
|
+
|
|
62
|
+
Returns:
|
|
63
|
+
The created user object with generated ID.
|
|
64
|
+
|
|
65
|
+
Raises:
|
|
66
|
+
ValidationError: If name or email are invalid.
|
|
67
|
+
ConflictError: If email already exists.
|
|
68
|
+
"""
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Python — NumPy Style Docstrings
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
def create_user(name: str, email: str) -> User:
|
|
77
|
+
"""Create a new user in the system.
|
|
78
|
+
|
|
79
|
+
Parameters
|
|
80
|
+
----------
|
|
81
|
+
name : str
|
|
82
|
+
The user's display name (2-50 chars).
|
|
83
|
+
email : str
|
|
84
|
+
The user's email address (must be unique).
|
|
85
|
+
|
|
86
|
+
Returns
|
|
87
|
+
-------
|
|
88
|
+
User
|
|
89
|
+
The created user object with generated ID.
|
|
90
|
+
|
|
91
|
+
Raises
|
|
92
|
+
------
|
|
93
|
+
ValidationError
|
|
94
|
+
If name or email are invalid.
|
|
95
|
+
"""
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Python — reST Style (Sphinx)
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
def create_user(name: str, email: str) -> User:
|
|
104
|
+
"""Create a new user in the system.
|
|
105
|
+
|
|
106
|
+
:param name: The user's display name (2-50 chars).
|
|
107
|
+
:param email: The user's email address (must be unique).
|
|
108
|
+
:returns: The created user object with generated ID.
|
|
109
|
+
:raises ValidationError: If name or email are invalid.
|
|
110
|
+
:raises ConflictError: If email already exists.
|
|
111
|
+
"""
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Rust — rustdoc
|
|
117
|
+
|
|
118
|
+
```rust
|
|
119
|
+
/// Creates a new user in the system.
|
|
120
|
+
///
|
|
121
|
+
/// # Arguments
|
|
122
|
+
/// * `name` - The user's display name (2-50 chars)
|
|
123
|
+
/// * `email` - The user's email address (must be unique)
|
|
124
|
+
///
|
|
125
|
+
/// # Returns
|
|
126
|
+
/// The created `User` object
|
|
127
|
+
///
|
|
128
|
+
/// # Errors
|
|
129
|
+
/// Returns `ValidationError` if name or email are invalid.
|
|
130
|
+
/// Returns `ConflictError` if email already exists.
|
|
131
|
+
///
|
|
132
|
+
/// # Example
|
|
133
|
+
/// ```rust
|
|
134
|
+
/// let user = create_user("Alice", "alice@test.com")?;
|
|
135
|
+
/// ```
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Go — Godoc
|
|
141
|
+
|
|
142
|
+
```go
|
|
143
|
+
// CreateUser creates a new user in the system.
|
|
144
|
+
// It validates the input and checks for duplicate emails.
|
|
145
|
+
//
|
|
146
|
+
// Parameters:
|
|
147
|
+
// - name: the user's display name (2-50 chars)
|
|
148
|
+
// - email: the user's email address (must be unique)
|
|
149
|
+
//
|
|
150
|
+
// Returns the created user, or an error if validation fails
|
|
151
|
+
// or the email already exists.
|
|
152
|
+
func CreateUser(name string, email string) (*User, error) {
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Godoc Conventions
|
|
156
|
+
- First sentence is the summary (used in `go doc` listing)
|
|
157
|
+
- Use full sentences with proper punctuation
|
|
158
|
+
- Document function behavior, not implementation
|
|
159
|
+
- `//` only, no `/* */`
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## ADR Template
|
|
164
|
+
|
|
165
|
+
```markdown
|
|
166
|
+
# ADR-001: Use PostgreSQL for Primary Database
|
|
167
|
+
|
|
168
|
+
**Date:** 2026-05-25
|
|
169
|
+
**Status:** Accepted
|
|
170
|
+
|
|
171
|
+
## Context
|
|
172
|
+
We need a primary database for storing user data.
|
|
173
|
+
The system needs strong consistency and complex queries.
|
|
174
|
+
|
|
175
|
+
## Decision
|
|
176
|
+
Use PostgreSQL 16 as the primary database.
|
|
177
|
+
|
|
178
|
+
## Consequences
|
|
179
|
+
- ✅ Strong consistency with ACID transactions
|
|
180
|
+
- ✅ Rich query capabilities (JSON, full-text search)
|
|
181
|
+
- ⚠️ Requires managed database service (increased cost)
|
|
182
|
+
- ⚠️ Schema migrations need careful planning
|
|
183
|
+
|
|
184
|
+
## Alternatives Considered
|
|
185
|
+
- MySQL: Similar capabilities but weaker JSON support
|
|
186
|
+
- MongoDB: Better horizontal scaling but eventual consistency
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
ADR numbering: sequential (`ADR-001`, `ADR-002`). Location: `docs/adr/`.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## CHANGELOG Template
|
|
194
|
+
|
|
195
|
+
```markdown
|
|
196
|
+
# Changelog
|
|
197
|
+
|
|
198
|
+
## [1.2.0] - 2026-05-25
|
|
199
|
+
|
|
200
|
+
### Added
|
|
201
|
+
- User creation API endpoint (POST /api/users)
|
|
202
|
+
- Email validation utility
|
|
203
|
+
|
|
204
|
+
### Changed
|
|
205
|
+
- Upgraded Express from 4.18 to 4.21
|
|
206
|
+
- Rate limiting now applied to all endpoints
|
|
207
|
+
|
|
208
|
+
### Fixed
|
|
209
|
+
- Memory leak in WebSocket connections
|
|
210
|
+
- Edge case in date parsing for timezone offsets
|
|
211
|
+
|
|
212
|
+
### Security
|
|
213
|
+
- Updated bcrypt dependency to patch CVE-2026-XXXX
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Follow [Keep a Changelog](https://keepachangelog.com) convention unless project uses custom format.
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: orchestrate
|
|
3
|
+
description: |
|
|
4
|
+
Multi-agent orchestration for complex development tasks. Breaks down large work, delegates to specialized agents, manages contracts, and drives the fix loop.
|
|
5
|
+
Use when tasks span multiple domains, require parallel execution, or need full lifecycle management.
|
|
6
|
+
Triggers on: "orchestrate", "coordinate", "manage", "run the full pipeline", "team", "complex task"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Orchestrate
|
|
10
|
+
|
|
11
|
+
Multi-agent orchestration workflow for complex development tasks.
|
|
12
|
+
|
|
13
|
+
## When to Use
|
|
14
|
+
|
|
15
|
+
- Task is too large for a single agent
|
|
16
|
+
- Task spans multiple domains (frontend + backend + infra)
|
|
17
|
+
- Need parallel execution of independent subtasks
|
|
18
|
+
- Full lifecycle management from architecture to merge
|
|
19
|
+
|
|
20
|
+
## Comparison with fullstack-dev
|
|
21
|
+
|
|
22
|
+
| Aspect | fullstack-dev | team-lead |
|
|
23
|
+
|--------|---------------|-----------|
|
|
24
|
+
| Scope | Single feature | Multi-domain, complex tasks |
|
|
25
|
+
| Parallelism | Sequential phases | Parallel subtask execution |
|
|
26
|
+
| Delegation | One agent per phase | Multiple agents concurrently |
|
|
27
|
+
| State | Single contract chain | Parallel + merge contracts |
|
|
28
|
+
| Best for | Well-defined changes | Large features, refactors, cross-cutting work |
|
|
29
|
+
|
|
30
|
+
## Workflow
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
Task Intake → Decomposition → Parallel Dispatch → Collection → Synthesis → Review → Done
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Step 1: Task Intake
|
|
37
|
+
|
|
38
|
+
Analyze the user's request and determine scope:
|
|
39
|
+
- **Simple** (≤3 files, single domain) → delegate to fullstack-dev
|
|
40
|
+
- **Complex** (multi-domain, large scope) → orchestrate here
|
|
41
|
+
|
|
42
|
+
Ask clarifying questions if needed (one at a time with rationale).
|
|
43
|
+
|
|
44
|
+
### Step 2: Decomposition
|
|
45
|
+
|
|
46
|
+
Break the task into manageable subtasks, each with:
|
|
47
|
+
- Clear input/output
|
|
48
|
+
- Assigned agent type
|
|
49
|
+
- Dependencies between subtasks
|
|
50
|
+
- Whether an ADR or contract is needed first
|
|
51
|
+
|
|
52
|
+
### Step 3: Parallel Dispatch
|
|
53
|
+
|
|
54
|
+
Launch independent subtasks concurrently using the Task tool with appropriate `subagent_type`:
|
|
55
|
+
|
|
56
|
+
```markdown
|
|
57
|
+
Task 1: architect (ADR for infrastructure choice)
|
|
58
|
+
Task 2: spec-writer (contract for API design)
|
|
59
|
+
(These are independent — launch in parallel)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Dependent subtasks run sequentially:
|
|
63
|
+
```
|
|
64
|
+
Task 1: architect (ADR) → Task 2: spec-writer (contract) → Task 3: executor (implement)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Step 4: Collection
|
|
68
|
+
|
|
69
|
+
Read contract outputs from `docs/adr/` and `docs/specs/` for each subtask.
|
|
70
|
+
Resolve conflicts between parallel streams.
|
|
71
|
+
|
|
72
|
+
### Step 5: Synthesis
|
|
73
|
+
|
|
74
|
+
Combine parallel results into a coherent whole. Write `.handoffs/orchestrate/synthesis.md` with:
|
|
75
|
+
- What each subtask produced
|
|
76
|
+
- Integration notes
|
|
77
|
+
- Remaining work
|
|
78
|
+
- Risks discovered
|
|
79
|
+
|
|
80
|
+
### Step 6: Review
|
|
81
|
+
|
|
82
|
+
Run pr-review on the synthesized result:
|
|
83
|
+
- Delegate to code-reviewer agent
|
|
84
|
+
- Apply fixes if issues found
|
|
85
|
+
- Check that all architectural decisions have ADRs
|
|
86
|
+
|
|
87
|
+
### Step 7: Verification
|
|
88
|
+
|
|
89
|
+
Run tests:
|
|
90
|
+
- Delegate to test-engineer for new test generation
|
|
91
|
+
- Delegate to verifier for full test suite run
|
|
92
|
+
|
|
93
|
+
## Artifact Summary
|
|
94
|
+
|
|
95
|
+
| Artifact | Location | Persistent | Purpose |
|
|
96
|
+
|----------|----------|------------|---------|
|
|
97
|
+
| ADR | `docs/adr/NNNN-title.md` | ✅ Committed | Architecture decisions |
|
|
98
|
+
| Contract | `docs/specs/<feature>/` | ✅ Committed | Requirements, ACs, API |
|
|
99
|
+
| Synthesis | `.handoffs/orchestrate/synthesis.md` | ❌ Temporary | Merge notes |
|
|
100
|
+
|
|
101
|
+
## Handoff Directory
|
|
102
|
+
|
|
103
|
+
All orchestration state: `.handoffs/orchestrate/`
|
|
104
|
+
|
|
105
|
+
## Error Recovery
|
|
106
|
+
|
|
107
|
+
| Failure | Action |
|
|
108
|
+
|---------|--------|
|
|
109
|
+
| Subtask fails | Retry once, then report to user |
|
|
110
|
+
| Parallel conflicts | Reconcile in synthesis phase |
|
|
111
|
+
| Verification fails | Enter fix loop (max 3 retries) |
|
|
112
|
+
| User changes mind | Accept new direction, re-plan affected subtasks |
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Orchestration Patterns
|
|
2
|
+
|
|
3
|
+
## Decomposition Strategies
|
|
4
|
+
|
|
5
|
+
### By Layer (frontend/backend/infra)
|
|
6
|
+
```
|
|
7
|
+
Frontend (executor) ─┐
|
|
8
|
+
Backend (executor) ├─→ Synthesis → Review
|
|
9
|
+
Infra (executor) ┘
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
### By Phase (plan/implement/verify)
|
|
13
|
+
```
|
|
14
|
+
Planner ─→ Executor ─→ Verifier
|
|
15
|
+
(sequential pipeline)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### By Concern (feature A / feature B)
|
|
19
|
+
```
|
|
20
|
+
Planner (feature A) ─→ Executor (A) ─→ Verifier (A) ─┐
|
|
21
|
+
├─→ Synthesis
|
|
22
|
+
Planner (feature B) ─→ Executor (B) ─→ Verifier (B) ─┘
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Agent Dispatch Reference
|
|
26
|
+
|
|
27
|
+
| Subtask Type | Agent | Max Parallel |
|
|
28
|
+
|-------------|-------|-------------|
|
|
29
|
+
| Architecture/planning | spec-writer | 3 |
|
|
30
|
+
| Implementation | executor | 5 |
|
|
31
|
+
| Code review | code-reviewer | 3 |
|
|
32
|
+
| Test generation | test-engineer | 3 |
|
|
33
|
+
| Verification | verifier | 1 |
|
|
34
|
+
|
|
35
|
+
## Handoff Format
|
|
36
|
+
|
|
37
|
+
All handoffs in `.handoffs/orchestrate/` follow this structure:
|
|
38
|
+
|
|
39
|
+
```markdown
|
|
40
|
+
## Subtask: <name>
|
|
41
|
+
**Agent:** <type>
|
|
42
|
+
**Status:** completed / failed / skipped
|
|
43
|
+
|
|
44
|
+
### Input
|
|
45
|
+
- <what was given to the agent>
|
|
46
|
+
|
|
47
|
+
### Output
|
|
48
|
+
- <what the agent produced>
|
|
49
|
+
|
|
50
|
+
### Files Changed
|
|
51
|
+
- path/to/file.ts (modified)
|
|
52
|
+
- path/to/new.test.ts (added)
|
|
53
|
+
|
|
54
|
+
### Notes
|
|
55
|
+
- <deviations, risks, pending items>
|
|
56
|
+
```
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pr-review
|
|
3
|
+
description: |
|
|
4
|
+
Systematic code review for pull requests. Analyzes diff across 5 dimensions:
|
|
5
|
+
correctness, security, quality, testing, and style.
|
|
6
|
+
Use PROACTIVELY when reviewing PRs, analyzing code changes, or asked to "review", "audit", "check".
|
|
7
|
+
Triggers on: "review this PR", "code review", "review changes", "audit", "check my code"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# PR Review
|
|
11
|
+
|
|
12
|
+
Systematic pull request review across 5 dimensions: Correctness, Security, Code Quality, Testing, and Style.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- Reviewing a PR before merge
|
|
17
|
+
- Analyzing a diff for potential issues
|
|
18
|
+
- Preparing review comments for a colleague
|
|
19
|
+
- Auditing code changes for security or quality
|
|
20
|
+
|
|
21
|
+
## Review Workflow
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
Diff Input → 5-Dimension Analysis → Issue Classification → Review Report
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Step 1: Input Preparation
|
|
28
|
+
|
|
29
|
+
Determine what to review:
|
|
30
|
+
|
|
31
|
+
- **Branch diff:** `git diff main...HEAD` or `git diff <base>...<feature>`
|
|
32
|
+
- **Staged changes:** `git diff --cached`
|
|
33
|
+
- **Specific files:** `git diff <base>...<feature> -- <paths>`
|
|
34
|
+
- **GitHub PR:** Use `gh` CLI to fetch PR details and diff
|
|
35
|
+
|
|
36
|
+
Collect context:
|
|
37
|
+
- Read commit messages for intent
|
|
38
|
+
- Check linked issues if available
|
|
39
|
+
- Note which files are changed (added/modified/deleted)
|
|
40
|
+
|
|
41
|
+
### Step 2: 5-Dimension Analysis
|
|
42
|
+
|
|
43
|
+
Each dimension has specific checks:
|
|
44
|
+
|
|
45
|
+
| Dimension | Focus | Key Questions |
|
|
46
|
+
|-----------|-------|---------------|
|
|
47
|
+
| **Correctness** | Logic, edge cases, contracts | Does the code do what it intends? Are edge cases handled? Are there off-by-one, race conditions, or null dereferences? |
|
|
48
|
+
| **Security** | Vulnerabilities, hardening | Are inputs validated? Are there injection risks? Secrets exposed? Authz checks in place? |
|
|
49
|
+
| **Code Quality** | Maintainability, patterns | Does it follow project conventions? Is it readable? Over-engineering? Dead code? Tech debt introduced? |
|
|
50
|
+
| **Testing** | Coverage, test quality | Are new changes tested? Are tests meaningful? Edge cases covered? Test maintainability? |
|
|
51
|
+
| **Style** | Formatting, naming | Consistent with project style? Meaningful names? No unnecessary formatting changes mixed in? |
|
|
52
|
+
|
|
53
|
+
See `references/review-dimensions.md` for detailed per-dimension checklists.
|
|
54
|
+
|
|
55
|
+
### Step 3: Issue Classification
|
|
56
|
+
|
|
57
|
+
Each finding is classified by severity:
|
|
58
|
+
|
|
59
|
+
- **🔴 BLOCKING** — Must fix before merge (bug, security vulnerability, data loss)
|
|
60
|
+
- **🟡 WARNING** — Should fix (code smell, missing edge case, weak test)
|
|
61
|
+
- **🔵 SUGGESTION** — Nice to have (style preference, optional refactor)
|
|
62
|
+
- **⚪ PRAISE** — Positive feedback (good design, clever solution, thorough tests)
|
|
63
|
+
|
|
64
|
+
### Step 4: Output Report
|
|
65
|
+
|
|
66
|
+
Write review report to stdout with this structure:
|
|
67
|
+
|
|
68
|
+
```markdown
|
|
69
|
+
## PR Review: <brief title>
|
|
70
|
+
|
|
71
|
+
### Overview
|
|
72
|
+
<summary of changes, files changed (+/- stats), general assessment>
|
|
73
|
+
|
|
74
|
+
### Findings
|
|
75
|
+
|
|
76
|
+
#### 🔴 <issue title>
|
|
77
|
+
- **File:** `path/to/file.ts:42`
|
|
78
|
+
- **Severity:** blocking
|
|
79
|
+
- **Description:** <what and why>
|
|
80
|
+
- **Suggestion:** <how to fix>
|
|
81
|
+
|
|
82
|
+
... (more findings) ...
|
|
83
|
+
|
|
84
|
+
### Summary
|
|
85
|
+
- 🔴 Blocking: <count>
|
|
86
|
+
- 🟡 Warnings: <count>
|
|
87
|
+
- 🔵 Suggestions: <count>
|
|
88
|
+
- ⚪ Praise: <count>
|
|
89
|
+
- **Verdict:** Approve / Changes Requested / Needs Discussion
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Guiding Principles
|
|
93
|
+
|
|
94
|
+
1. **Be specific** — reference exact line numbers and file paths
|
|
95
|
+
2. **Explain why** — don't just say "this is wrong", explain the impact
|
|
96
|
+
3. **Offer solutions** — suggest concrete fixes, not just problems
|
|
97
|
+
4. **Prioritize** — focus on correctness and security over style
|
|
98
|
+
5. **Be constructive** — include praise for good code
|
|
99
|
+
|
|
100
|
+
## Anti-Patterns
|
|
101
|
+
|
|
102
|
+
- ❌ Nitpicking style while ignoring logic bugs
|
|
103
|
+
- ❌ Reviewing without reading full context (imports, types, etc.)
|
|
104
|
+
- ❌ Demanding changes without understanding tradeoffs
|
|
105
|
+
- ❌ Only negative feedback — missing good patterns
|
|
106
|
+
- ❌ Superficial review (LGTM without reading diff)
|
|
107
|
+
|
|
108
|
+
## Related Skills
|
|
109
|
+
|
|
110
|
+
- `dev-flow` — For implementing the fixes identified in review
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Review Dimensions — Detailed Checklists
|
|
2
|
+
|
|
3
|
+
## 1. Correctness
|
|
4
|
+
|
|
5
|
+
### Logic
|
|
6
|
+
- [ ] Does the code correctly implement the intended behavior?
|
|
7
|
+
- [ ] Are all branches of conditionals covered?
|
|
8
|
+
- [ ] Are loop boundaries correct (off-by-one)?
|
|
9
|
+
- [ ] Return values handled properly?
|
|
10
|
+
- [ ] Error paths don't silently swallow exceptions?
|
|
11
|
+
|
|
12
|
+
### Data Flow
|
|
13
|
+
- [ ] Data transformations preserve invariants?
|
|
14
|
+
- [ ] No unintended mutation of inputs?
|
|
15
|
+
- [ ] Null/undefined/optional values handled?
|
|
16
|
+
- [ ] Type assertions safe?
|
|
17
|
+
|
|
18
|
+
### Concurrency
|
|
19
|
+
- [ ] Shared state properly synchronized?
|
|
20
|
+
- [ ] No deadlock or race condition risk?
|
|
21
|
+
- [ ] Async operations have proper error handling?
|
|
22
|
+
- [ ] Resource cleanup guaranteed (finally, dispose, defer)?
|
|
23
|
+
|
|
24
|
+
### Edge Cases
|
|
25
|
+
- [ ] Empty collections handled?
|
|
26
|
+
- [ ] Boundary values (max int, empty string, zero)?
|
|
27
|
+
- [ ] Network/filesystem failures?
|
|
28
|
+
- [ ] Unexpected input formats?
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 2. Security
|
|
33
|
+
|
|
34
|
+
### Input Validation
|
|
35
|
+
- [ ] All user inputs validated (type, range, format)?
|
|
36
|
+
- [ ] Injection prevention (SQL, command, XSS, path traversal)?
|
|
37
|
+
- [ ] File uploads validated (type, size, content)?
|
|
38
|
+
- [ ] URLs/redirects validated against open redirect?
|
|
39
|
+
|
|
40
|
+
### Authentication & Authorization
|
|
41
|
+
- [ ] Auth checks on all protected endpoints?
|
|
42
|
+
- [ ] Principle of least privilege followed?
|
|
43
|
+
- [ ] No auth bypass paths?
|
|
44
|
+
- [ ] Session management secure?
|
|
45
|
+
|
|
46
|
+
### Data Protection
|
|
47
|
+
- [ ] No secrets in code, logs, or error messages?
|
|
48
|
+
- [ ] Sensitive data encrypted at rest and in transit?
|
|
49
|
+
- [ ] PII handled according to regulations?
|
|
50
|
+
- [ ] Temporary files cleaned up?
|
|
51
|
+
|
|
52
|
+
### Dependencies
|
|
53
|
+
- [ ] New dependencies necessary? Any known vulnerabilities?
|
|
54
|
+
- [ ] Versions pinned?
|
|
55
|
+
|
|
56
|
+
See `references/security-checklist.md` for language-specific security patterns.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 3. Code Quality
|
|
61
|
+
|
|
62
|
+
### Design
|
|
63
|
+
- [ ] Follows single responsibility principle?
|
|
64
|
+
- [ ] Good separation of concerns?
|
|
65
|
+
- [ ] Appropriate abstraction level (not over/under-engineered)?
|
|
66
|
+
- [ ] Follows project's architectural patterns?
|
|
67
|
+
|
|
68
|
+
### Readability
|
|
69
|
+
- [ ] Meaningful names (functions, variables, classes)?
|
|
70
|
+
- [ ] Functions do one thing (not too long)?
|
|
71
|
+
- [ ] Comments explain "why", not "what"?
|
|
72
|
+
- [ ] No commented-out code?
|
|
73
|
+
|
|
74
|
+
### Maintainability
|
|
75
|
+
- [ ] No duplicated code (DRY)?
|
|
76
|
+
- [ ] Dependencies explicit (not hidden globals)?
|
|
77
|
+
- [ ] Config/hardcoded values in right place?
|
|
78
|
+
- [ ] Backward compatibility considered?
|
|
79
|
+
|
|
80
|
+
### Performance
|
|
81
|
+
- [ ] No obvious performance issues (N+1 queries, unnecessary allocations)?
|
|
82
|
+
- [ ] Resource cleanup (connections, file handles, memory)?
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 4. Testing
|
|
87
|
+
|
|
88
|
+
### Coverage
|
|
89
|
+
- [ ] New code has corresponding tests?
|
|
90
|
+
- [ ] Happy path tested?
|
|
91
|
+
- [ ] Error/edge case paths tested?
|
|
92
|
+
- [ ] Integration points tested?
|
|
93
|
+
|
|
94
|
+
### Test Quality
|
|
95
|
+
- [ ] Tests deterministic (no flakiness)?
|
|
96
|
+
- [ ] Tests independent (no shared mutable state)?
|
|
97
|
+
- [ ] Test names describe behavior, not implementation?
|
|
98
|
+
- [ ] No test logic in production code?
|
|
99
|
+
|
|
100
|
+
### Test Maintenance
|
|
101
|
+
- [ ] Tests not too brittle (testing behavior, not implementation)?
|
|
102
|
+
- [ ] No excessive mocking?
|
|
103
|
+
- [ ] Test data clear and maintainable?
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 5. Style
|
|
108
|
+
|
|
109
|
+
### Consistency
|
|
110
|
+
- [ ] Follows project's lint/format config?
|
|
111
|
+
- [ ] Naming conventions consistent (camelCase, PascalCase, etc.)?
|
|
112
|
+
- [ ] Import/style order consistent?
|
|
113
|
+
|
|
114
|
+
### Diff Hygiene
|
|
115
|
+
- [ ] No formatting-only changes mixed with logic changes?
|
|
116
|
+
- [ ] No unrelated files changed?
|
|
117
|
+
- [ ] Commit messages descriptive?
|