18 KiB
18 KiB
| description | allowed-tools | agents |
|---|---|---|
| Review implementation (Reviewer agent) | Read, Bash | 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)
- MUST run all validation checks (build, typecheck, lint, test, API contract)
- MUST verify every file in task's
file_pathsexists - MUST read and analyze each implemented file
- MUST check against acceptance_criteria in task file
- MUST output structured review report (format below)
- MUST run workflow_manager.py to update task status
CANNOT DO (Strictly Forbidden)
- CANNOT create files (Write tool blocked)
- CANNOT modify files (Edit tool blocked)
- CANNOT fix issues yourself - only report them
- CANNOT approve tasks with missing files
- CANNOT approve if ANY validation check fails
- 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]
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
npm run build 2>&1
BUILD_EXIT=$?
echo "BUILD_EXIT=$BUILD_EXIT"
2.2 TypeScript Strict Check
npx tsc --noEmit 2>&1
TS_EXIT=$?
echo "TS_EXIT=$TS_EXIT"
2.3 Async/Await Check [MANDATORY]
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()withoutawait.json()withoutawaitPromise.all()withoutawait- 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)
npm run lint 2>&1
LINT_EXIT=$?
echo "LINT_EXIT=$LINT_EXIT"
2.5 Unit Tests (if --strict or --full)
npm test -- --passWithNoTests 2>&1
TEST_EXIT=$?
echo "TEST_EXIT=$TEST_EXIT"
2.6 API Contract Validation [MANDATORY]
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]
# 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]
# 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]
ls $TASKS_DIR/*.yml 2>/dev/null
MUST process ALL task files found
Step A4: Review Each Task [MANDATORY]
For EACH task file:
# Extract file_paths from task
TASK_FILES=$(grep -A 20 "file_paths:" "$TASK_FILE" | grep -E "^\s+-" | sed 's/.*- //')
Check each file exists:
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:
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> approved
For REJECTED tasks:
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]
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
IF --next:
# 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:
TASK_FILE="$TASKS_DIR/$ARGUMENTS.yml"
BLOCK IF: Task file does not exist -> Error: "Task not found: $ARGUMENTS"
Step S2: Read Task Spec [MANDATORY]
cat "$TASK_FILE"
Extract:
id: Task identifierfile_paths: List of files to verifyacceptance_criteria: List of requirements to check
Step S3: Run All Validations [MANDATORY]
# 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:
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:
- Read file content
- Check against acceptance_criteria:
- File exports correct components/functions
- Props/types match manifest spec
- Code follows project patterns
- No obvious bugs or issues
- 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:
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID approved
IF REQUEST_CHANGES:
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
# 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.tsexports (GET, POST, PUT, DELETE) - Next.js Pages Router:
pages/api/*.tswith req.method checks - Express-style: router.get/post/etc patterns
Validation Rules
- Endpoint Existence: Every frontend call must have a matching backend route
- Method Match: GET calls must hit GET endpoints, POST to POST, etc.
- Body Alignment: POST/PUT calls should send bodies, GET should not
- 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