ai-apps
/
project-standalo-note-to-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
project-standalo-note-to-app/.claude/commands/workflow/review.md

570 lines
18 KiB
Markdown
Raw Blame History

---
description: Review implementation (Reviewer agent)
allowed-tools: Read, Bash
agents: workflow-reviewer, workflow-validator
---
# Reviewer Agent - Review Mode
**Input**: "$ARGUMENTS"
---
## CRITICAL ENFORCEMENT RULES
**YOU ARE IN READ-ONLY MODE. VIOLATIONS WILL BE BLOCKED.**
### MUST DO (Non-Negotiable)
1. **MUST** run all validation checks (build, typecheck, lint, test, API contract)
2. **MUST** verify every file in task's `file_paths` exists
3. **MUST** read and analyze each implemented file
4. **MUST** check against acceptance_criteria in task file
5. **MUST** output structured review report (format below)
6. **MUST** run workflow_manager.py to update task status
### CANNOT DO (Strictly Forbidden)
1. **CANNOT** create files (Write tool blocked)
2. **CANNOT** modify files (Edit tool blocked)
3. **CANNOT** fix issues yourself - only report them
4. **CANNOT** approve tasks with missing files
5. **CANNOT** approve if ANY validation check fails
6. **CANNOT** skip any validation check
### ALLOWED ACTIONS
- Read any file
- Run Bash commands (build, lint, test, typecheck, ls, cat, grep)
- Output review reports
- Update task status via workflow_manager.py
---
## VALIDATION CHECKS MATRIX
| Check | Command | Blocks Approval | When |
|-------|---------|-----------------|------|
| Build | `npm run build` | YES | Always |
| TypeScript | `npx tsc --noEmit` | YES | Always |
| Async/Await | `python3 verify_async.py` | YES | Always |
| Lint | `npm run lint` | YES (if --strict) | --strict mode |
| Unit Tests | `npm test -- --passWithNoTests` | YES (if --strict) | --strict mode |
| API Contract | `python3 validate_api_contract.py` | YES | Always |
| **Relations** | `python3 validate_relations.py` | YES | Always |
| Security Scan | `python3 security_scan.py` | YES (critical) | Always |
| Files Exist | `ls -la` each file | YES | Always |
**Note:** For comprehensive security audit, use `/workflow:security --full`
---
## ARGUMENT PARSING
```
IF "$ARGUMENTS" contains "--auto":
MODE = AUTO (batch review all tasks)
STRICT = "$ARGUMENTS" contains "--strict"
FULL = "$ARGUMENTS" contains "--full"
ELSE IF "$ARGUMENTS" = "--next":
MODE = SINGLE (next pending task)
ELSE:
MODE = SINGLE (specific task: "$ARGUMENTS")
```
---
## MODE: AUTO REVIEW (--auto)
### Step A1: Get Active Version [MANDATORY]
```bash
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
```
### Step A2: Run Global Validations [MANDATORY]
#### 2.1 Build Check
```bash
npm run build 2>&1
BUILD_EXIT=$?
echo "BUILD_EXIT=$BUILD_EXIT"
```
#### 2.2 TypeScript Strict Check
```bash
npx tsc --noEmit 2>&1
TS_EXIT=$?
echo "TS_EXIT=$TS_EXIT"
```
#### 2.3 Async/Await Check [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/verify_async.py --path . 2>&1
ASYNC_EXIT=$?
echo "ASYNC_EXIT=$ASYNC_EXIT"
```
This catches runtime errors at build time:
- `fetch()` without `await`
- `.json()` without `await`
- `Promise.all()` without `await`
- Floating promises (unawaited async calls)
**Exit codes:**
- 0 = PASS (no high-severity issues)
- 1 = HIGH severity issues found (blocks approval)
#### 2.4 Lint Check (if --strict or --full)
```bash
npm run lint 2>&1
LINT_EXIT=$?
echo "LINT_EXIT=$LINT_EXIT"
```
#### 2.5 Unit Tests (if --strict or --full)
```bash
npm test -- --passWithNoTests 2>&1
TEST_EXIT=$?
echo "TEST_EXIT=$TEST_EXIT"
```
#### 2.6 API Contract Validation [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir . 2>&1
API_EXIT=$?
echo "API_EXIT=$API_EXIT"
```
This validates:
- Frontend API calls have matching backend endpoints
- HTTP methods match (GET, POST, PUT, DELETE)
- Request bodies are sent where expected
- Response handling matches backend output
#### 2.7 Relationship Chain Validation [MANDATORY]
```bash
# Build relations graph and validate alignment
python3 skills/guardrail-orchestrator/scripts/build_relations.py \
--project-dir . \
--output .workflow/relations.yml 2>&1
python3 skills/guardrail-orchestrator/scripts/validate_relations.py \
--project-dir . \
--relations .workflow/relations.yml 2>&1
RELATIONS_EXIT=$?
echo "RELATIONS_EXIT=$RELATIONS_EXIT"
```
This validates the full data flow chain:
- **Database → API**: API response types match database schema fields
- **API → Component**: Component props match API response types
- **Component → Page**: Pages correctly provide data to components
- **Reference integrity**: All dependencies exist
- **Layer violations**: Lower layers don't depend on higher layers
- **Circular dependencies**: No dependency cycles
**Exit codes:**
- 0 = PASS (all relationships valid)
- 1 = WARNINGS (type mismatches, missing chains)
- 2 = ERRORS (missing references, circular deps, layer violations)
#### 2.8 Security Scan [MANDATORY]
```bash
# Run comprehensive security scanner
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
--project-dir . \
--severity HIGH
SECURITY_EXIT=$?
echo "SECURITY_EXIT=$SECURITY_EXIT"
```
**Security scan checks:**
- Hardcoded secrets (API keys, passwords, tokens)
- SQL injection vulnerabilities
- XSS risks (dangerouslySetInnerHTML, innerHTML)
- Command injection patterns
- Path traversal vulnerabilities
- NoSQL injection risks
- SSRF vulnerabilities
- Prototype pollution
- Insecure authentication patterns
- CORS misconfigurations
- Sensitive data exposure
- Debug code in production
**Exit codes:**
- 0 = PASS (no critical/high issues)
- 1 = HIGH issues found (warning)
- 2 = CRITICAL issues found (blocks approval)
**For full security audit, run:** `/workflow:security --full`
### Step A3: Gather All Tasks [MANDATORY]
```bash
ls $TASKS_DIR/*.yml 2>/dev/null
```
**MUST process ALL task files found**
### Step A4: Review Each Task [MANDATORY]
For EACH task file:
```bash
# Extract file_paths from task
TASK_FILES=$(grep -A 20 "file_paths:" "$TASK_FILE" | grep -E "^\s+-" | sed 's/.*- //')
```
**Check each file exists**:
```bash
for file in $TASK_FILES; do
if [ -f "$file" ]; then
echo "EXISTS: $file"
else
echo "MISSING: $file"
MISSING_COUNT=$((MISSING_COUNT + 1))
fi
done
```
**Determine task verdict**:
```
IF all files exist
AND BUILD_EXIT = 0
AND TS_EXIT = 0
AND ASYNC_EXIT = 0
AND API_EXIT = 0
AND RELATIONS_EXIT != 2 (no critical relation errors)
AND SECURITY_EXIT != 2 (no critical security issues)
AND (not --strict OR (LINT_EXIT = 0 AND TEST_EXIT = 0)):
-> TASK_VERDICT = APPROVED
ELSE:
-> TASK_VERDICT = REJECTED
-> Record reason (missing files / build failure / type error / async issue / API mismatch / relation error / security issue)
```
**Security exit codes:**
- 0 = PASS
- 1 = HIGH issues (warning, doesn't block unless --strict)
- 2 = CRITICAL issues (always blocks)
### Step A5: Batch Update [MANDATORY]
For APPROVED tasks:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> approved
```
For REJECTED tasks:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> pending
```
### Step A6: Auto Review Report [MANDATORY]
**MUST output this exact format**:
```
+======================================================================+
| REVIEW COMPLETE |
+======================================================================+
| Version: $VERSION_ID |
| Mode: AUTO [STRICT if --strict] [FULL if --full] |
+======================================================================+
| VALIDATION RESULTS |
+----------------------------------------------------------------------+
| Build: PASS (exit 0) / FAIL (exit $BUILD_EXIT) |
| TypeScript: PASS (exit 0) / FAIL (exit $TS_EXIT) |
| Async/Await: PASS / FAIL (X high, Y medium issues) |
| Lint: PASS / FAIL / SKIPPED |
| Tests: PASS / FAIL / SKIPPED |
| API Contract: PASS / FAIL (X errors, Y warnings) |
| Relations: PASS / WARN / FAIL (X errors, Y warnings) |
| Security: PASS / WARNING / CRITICAL |
| (C:X H:X M:X L:X issues) |
+======================================================================+
| API CONTRACT DETAILS |
+----------------------------------------------------------------------+
| Frontend calls: X matched, Y unmatched |
| Backend endpoints: X defined, Y unused |
| Method mismatches: X |
| Body mismatches: X |
+======================================================================+
| RELATIONSHIP CHAIN DETAILS |
+----------------------------------------------------------------------+
| Entities: X total (DB:X API:X Comp:X Page:X) |
| Relations: X total |
| DB → API: X aligned, Y mismatches |
| API → Component: X aligned, Y mismatches |
| Component → Page: X aligned, Y mismatches |
| Circular deps: X detected |
| Layer violations: X detected |
+======================================================================+
| TASK RESULTS |
+----------------------------------------------------------------------+
| Total: X tasks |
| Approved: X tasks |
| Rejected: X tasks |
| Skipped: X tasks (already completed) |
+======================================================================+
| APPROVED TASKS |
| - task_create_Button |
| - task_create_Form |
+----------------------------------------------------------------------+
| REJECTED TASKS |
| - task_create_Modal |
| Reason: Missing file app/components/Modal.tsx |
| - task_update_API |
| Reason: API contract error - endpoint not found |
+======================================================================+
| SECURITY WARNINGS |
| - src/lib/api.ts:15 - Possible hardcoded API key |
| - app/page.tsx:42 - dangerouslySetInnerHTML usage |
+======================================================================+
```
### Step A7: Next Steps [MANDATORY]
**IF all approved**:
```
All tasks approved.
Next: Run `/workflow:approve implementation` to continue.
```
**IF any rejected**:
```
Some tasks need fixes.
API Contract Issues:
For frontend issues: Fix the API call URL or method
For backend issues: Create or fix the API endpoint
For each rejected task, run:
/workflow:frontend <task_id> (for frontend tasks)
/workflow:backend <task_id> (for backend tasks)
Then re-run: /workflow:review --auto
```
---
## MODE: SINGLE TASK REVIEW (--next or task_id)
### Step S1: Get Task [MANDATORY]
```bash
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
```
**IF --next**:
```bash
# Find first task with status: pending or status: implemented
TASK_FILE=$(grep -l "status: pending\|status: implemented" $TASKS_DIR/*.yml 2>/dev/null | head -1)
```
**IF specific task_id**:
```bash
TASK_FILE="$TASKS_DIR/$ARGUMENTS.yml"
```
**BLOCK IF**: Task file does not exist -> Error: "Task not found: $ARGUMENTS"
### Step S2: Read Task Spec [MANDATORY]
```bash
cat "$TASK_FILE"
```
Extract:
- `id`: Task identifier
- `file_paths`: List of files to verify
- `acceptance_criteria`: List of requirements to check
### Step S3: Run All Validations [MANDATORY]
```bash
# Build
npm run build 2>&1
BUILD_EXIT=$?
# TypeScript
npx tsc --noEmit 2>&1
TS_EXIT=$?
# API Contract
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir . 2>&1
API_EXIT=$?
```
**MUST capture and report all exit codes**
### Step S4: Verify Files Exist [MANDATORY]
For each path in `file_paths`:
```bash
ls -la "$path" 2>/dev/null && echo "EXISTS" || echo "MISSING"
```
**Record**:
- FILES_EXIST = true/false
- MISSING_FILES = list of missing paths
### Step S5: Read and Analyze Files [MANDATORY]
For each EXISTING file:
1. Read file content
2. Check against acceptance_criteria:
- [ ] File exports correct components/functions
- [ ] Props/types match manifest spec
- [ ] Code follows project patterns
- [ ] No obvious bugs or issues
3. Check API contract compliance:
- [ ] Frontend calls use correct endpoints
- [ ] HTTP methods are appropriate
- [ ] Request bodies are properly structured
- [ ] Response handling is correct
### Step S6: Determine Verdict [MANDATORY]
```
IF BUILD_EXIT = 0
AND TS_EXIT = 0
AND API_EXIT = 0
AND FILES_EXIST = true
AND acceptance_criteria met:
-> VERDICT = APPROVED
ELSE:
-> VERDICT = REQUEST_CHANGES
-> Record all issues found
```
### Step S7: Update Task Status [MANDATORY]
**IF APPROVED**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID approved
```
**IF REQUEST_CHANGES**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID pending
```
### Step S8: Output Review Report [MANDATORY]
**MUST output this exact format**:
```
+======================================================================+
| TASK REVIEW |
+======================================================================+
| Task: $TASK_ID |
| Version: $VERSION_ID |
+======================================================================+
| VALIDATION CHECKS |
+----------------------------------------------------------------------+
| Build: PASS / FAIL |
| TypeScript: PASS / FAIL |
| API Contract: PASS / FAIL |
| Files exist: PASS / FAIL (X/Y files) |
| Acceptance criteria: PASS / PARTIAL / FAIL |
| Code quality: PASS / ISSUES |
+======================================================================+
| API CONTRACT STATUS |
+----------------------------------------------------------------------+
| Endpoint calls: X found, Y matched |
| Method correctness: PASS / X mismatches |
| Request bodies: PASS / X issues |
| Response handling: PASS / ISSUES |
+======================================================================+
| VERDICT: APPROVED / REQUEST_CHANGES |
+======================================================================+
| [If REQUEST_CHANGES, list all issues:] |
| 1. Missing file: app/components/Button.tsx |
| 2. TypeScript error: Type 'string' not assignable to 'number' |
| 3. API contract: POST /api/users called but endpoint expects GET |
| 4. API contract: Frontend sends body but backend ignores it |
| 5. Acceptance criterion not met: "Must support dark mode" |
+======================================================================+
```
### Step S9: Next Steps [MANDATORY]
**IF APPROVED**:
```
Task approved.
Next: Run `/workflow:complete $TASK_ID` to mark as done.
Or run `/workflow:review --next` to review next task.
```
**IF REQUEST_CHANGES**:
```
Changes requested.
Issues to fix:
[List specific issues with file locations]
For API contract issues:
- If frontend issue: Fix the fetch/axios call in [file:line]
- If backend issue: Update the API route handler in [file]
Fix issues and re-run:
/workflow:frontend $TASK_ID (for frontend tasks)
/workflow:backend $TASK_ID (for backend tasks)
Then: /workflow:review $TASK_ID
```
---
## USAGE EXAMPLES
```bash
# Review specific task
/workflow:review task_create_Button
# Review next pending task
/workflow:review --next
# Auto-review all tasks (standard - build + types + API)
/workflow:review --auto
# Auto-review all tasks (strict - includes lint + tests)
/workflow:review --auto --strict
# Full review with all checks
/workflow:review --auto --full
```
---
## API CONTRACT VALIDATION DETAILS
The API contract validator checks:
### Frontend Analysis
- **fetch()** calls with `/api/` paths
- **axios** requests (get, post, put, delete)
- **useSWR** data fetching hooks
- **Custom API clients** (api.get, api.post, etc.)
### Backend Analysis
- **Next.js App Router**: `app/api/*/route.ts` exports (GET, POST, PUT, DELETE)
- **Next.js Pages Router**: `pages/api/*.ts` with req.method checks
- **Express-style**: router.get/post/etc patterns
### Validation Rules
1. **Endpoint Existence**: Every frontend call must have a matching backend route
2. **Method Match**: GET calls must hit GET endpoints, POST to POST, etc.
3. **Body Alignment**: POST/PUT calls should send bodies, GET should not
4. **Unused Endpoints**: Backend routes not called by frontend (warnings)
---
## ENFORCEMENT CHECKLIST
Before completing this command, verify:
- [ ] Build command executed and exit code captured
- [ ] TypeScript check executed and exit code captured
- [ ] Async/await validation executed and exit code captured
- [ ] API contract validation executed and exit code captured
- [ ] **Relationship chain validation executed and exit code captured**
- [ ] All file_paths verified with ls command
- [ ] Security scan completed
- [ ] Structured review report output (exact format above)
- [ ] Task status updated via workflow_manager.py
- [ ] Next steps clearly stated
Reference in New Issue View Git Blame Copy Permalink