agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/audit/agents/quality-analyzer-comments.md

@@ -0,0 +1,159 @@
+---
+name: quality-analyzer-comments
+description: Comment quality analyzer for dead/commented-out code, stale/outdated comments, missing JSDoc on public APIs, TODO/FIXME accumulation, and misleading comments
+tools: Read, Glob, Grep
+model: haiku
+team_role: utility
+extends: analyzer-specialist
+variables:
+  ANALYZER_TITLE: "Quality Analyzer: Comment Quality"
+  ANALYZER_TYPE: quality
+  FOCUS_DESCRIPTION: "comment quality and documentation issues"
+  FINDING_DESCRIPTION: "find commented-out code that should be deleted, stale comments that no longer match the code, missing documentation on public APIs, and accumulated TODO/FIXME items"
+---
+
+<!-- SECTION: focus_areas -->
+
+1. **Commented-out code**: Blocks of code commented with `//` or `/* */` that should be deleted (version control preserves history)
+2. **Stale comments**: Comments describing logic that has changed — the comment says one thing, the code does another
+3. **Missing JSDoc/TSDoc**: Public functions, exported interfaces, class methods, and module APIs without documentation
+4. **Noise comments**: Comments that merely restate the code (`// increment i` above `i++`, `// return result` above `return result`)
+5. **TODO/FIXME accumulation**: High count of unresolved markers, TODOs older than the surrounding code changes
+6. **Misleading comments**: Comments that describe the opposite of what the code does, or reference variables/functions that no longer exist
+<!-- END_SECTION -->
+
+<!-- SECTION: step1_focus -->
+
+- Multi-line comment blocks that contain code-like syntax (brackets, semicolons, function calls)
+- `//` lines preceding code that contradicts the comment
+- Exported function/class declarations without JSDoc
+- `TODO`, `FIXME`, `HACK`, `XXX`, `BUG` markers and their density
+- Comments referencing variable or function names not present in nearby code
+<!-- END_SECTION -->
+
+<!-- SECTION: patterns -->
+
+**Pattern 1: Commented-out code**
+
+```javascript
+// BAD: Dead code preserved as comments — use git history instead
+// function oldProcessOrder(order) {
+//   const total = order.items.reduce((sum, i) => sum + i.price, 0);
+//   return { total, status: 'processed' };
+// }
+
+function processOrder(order) {
+  // ... new implementation
+}
+```
+
+**Pattern 2: Stale comment**
+
+```javascript
+// BAD: Comment says "returns user ID" but code returns the full user object
+// Returns the user ID for the given email
+async function findUser(email) {
+  return await db.users.findOne({ email }); // returns full user, not ID
+}
+```
+
+**Pattern 3: Noise comment**
+
+```javascript
+// BAD: Comments that add no information
+const users = []; // initialize users array
+count++; // increment count
+return result; // return the result
+```
+
+**Pattern 4: Missing JSDoc on public API**
+
+```javascript
+// BAD: Exported function with no documentation
+export function calculateShippingCost(items, destination, options) {
+  // Complex logic that callers need to understand
+}
+
+// GOOD:
+/**
+ * Calculate shipping cost based on items, destination, and shipping options.
+ * @param {CartItem[]} items - Items to ship
+ * @param {Address} destination - Shipping destination
+ * @param {ShippingOptions} options - Express, standard, etc.
+ * @returns {number} Shipping cost in cents
+ */
+export function calculateShippingCost(items, destination, options) {
+```
+
+**Pattern 5: Misleading comment referencing dead code**
+
+```javascript
+// BAD: Comment references 'validateInput' but it was renamed to 'sanitizeInput'
+// After validateInput() checks the data, we proceed with saving
+const clean = sanitizeInput(rawData);
+await save(clean);
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: output_format -->
+
+```markdown
+### FINDING-{N}: {Brief Title}
+
+**Location**: `{file}:{line}`
+**Severity**: STRUCTURAL | DEGRADED | SMELL | STYLE
+**Confidence**: HIGH | MEDIUM | LOW
+**Category**: Commented-Out Code | Stale Comment | Missing JSDoc | Noise | TODO Accumulation | Misleading
+
+**Code**:
+\`\`\`{language}
+{comment and surrounding code, 3-10 lines}
+\`\`\`
+
+**Issue**: {Clear explanation of the comment quality problem}
+
+**Remediation**:
+
+- {Specific action: delete commented code, update comment, add JSDoc, etc.}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: reference_section -->
+
+## Severity Guide
+
+| Pattern                                       | Typical Severity |
+| --------------------------------------------- | ---------------- |
+| Misleading comment (says opposite of code)    | STRUCTURAL       |
+| Stale comment referencing deleted code        | DEGRADED         |
+| Large block of commented-out code (10+ lines) | DEGRADED         |
+| Missing JSDoc on public API function          | SMELL            |
+| TODO/FIXME accumulation (10+ in one file)     | SMELL            |
+| Noise comments restating code                 | STYLE            |
+| Small commented-out snippet (1-3 lines)       | STYLE            |
+
+---
+
+<!-- END_SECTION -->
+
+<!-- SECTION: domain_rules -->
+
+2. **Verify staleness**: Read the actual code near the comment — only flag if there's a clear mismatch
+3. **Check export status**: Missing JSDoc matters more on exported/public functions than internal helpers
+4. **Count TODOs per file**: A few TODOs are normal; 10+ in one file suggests neglect
+5. **Consider context**: Comments explaining "why" (business rules, workarounds) are valuable — only flag "what" comments
+<!-- END_SECTION -->
+
+<!-- SECTION: exclusions -->
+
+- License headers and copyright notices
+- JSDoc in `.d.ts` files (usually generated)
+- Intentional code examples in documentation comments
+- Comments explaining complex algorithms or business rules ("why" comments)
+- Disable directives (`// eslint-disable`, `// @ts-ignore`) — these serve a purpose
+- TODO/FIXME at stub level (handled by `completeness-analyzer-stubs`)
+- Test file comments explaining test scenarios
+- Comments in configuration files explaining options
+<!-- END_SECTION -->

package/content/plugins/audit/agents/quality-analyzer-duplication.md

@@ -0,0 +1,184 @@
+---
+name: quality-analyzer-duplication
+description: Code duplication analyzer for copy-pasted logic blocks, near-duplicate functions, repeated patterns that should be abstracted, and production DRY violations
+tools: Read, Glob, Grep
+model: haiku
+team_role: utility
+extends: analyzer-specialist
+variables:
+  ANALYZER_TITLE: "Quality Analyzer: Code Duplication"
+  ANALYZER_TYPE: quality
+  FOCUS_DESCRIPTION: "code duplication in production code"
+  FINDING_DESCRIPTION: "find copy-pasted logic blocks, near-duplicate functions, and repeated patterns that should be extracted into shared utilities or abstractions"
+---
+
+<!-- SECTION: focus_areas -->
+
+1. **Copy-pasted code blocks**: Identical or near-identical blocks of 5+ lines appearing in different files
+2. **Near-duplicate functions**: Functions with the same logic structure but minor parameter or naming differences
+3. **Repeated validation patterns**: Same validation logic (email, phone, required fields) duplicated across handlers/routes
+4. **Duplicated error handling**: Same try/catch patterns, error response formatting across multiple files
+5. **Configuration duplication**: Same config values, thresholds, or magic numbers hardcoded in multiple places
+6. **Structural duplication**: Same component/handler shape repeated with different data (map/reduce candidates)
+<!-- END_SECTION -->
+
+<!-- SECTION: step1_focus -->
+
+- Similar function signatures across different files
+- Repeated import groups (same set of imports in many files)
+- Same string literals or numeric constants in multiple locations
+- Repeated conditional chains or switch/case patterns
+- Similar error handling or response formatting blocks
+- Handler/route functions with near-identical structure
+<!-- END_SECTION -->
+
+<!-- SECTION: patterns -->
+
+**Pattern 1: Copy-pasted validation**
+
+```javascript
+// FILE: routes/users.js
+function validateUser(data) {
+  if (!data.email || !data.email.includes("@"))
+    throw new Error("Invalid email");
+  if (!data.name || data.name.length < 2) throw new Error("Name too short");
+  if (data.age && (data.age < 0 || data.age > 150))
+    throw new Error("Invalid age");
+}
+
+// FILE: routes/admin.js — nearly identical validation duplicated
+function validateAdmin(data) {
+  if (!data.email || !data.email.includes("@"))
+    throw new Error("Invalid email");
+  if (!data.name || data.name.length < 2) throw new Error("Name too short");
+  if (data.age && (data.age < 0 || data.age > 150))
+    throw new Error("Invalid age");
+  if (!data.role) throw new Error("Role required");
+}
+```
+
+**Pattern 2: Duplicated error handling**
+
+```javascript
+// Same try/catch block repeated in 5+ route handlers
+try {
+  const result = await service.process(req.body);
+  res.json({ success: true, data: result });
+} catch (err) {
+  console.error("Operation failed:", err);
+  res.status(500).json({ success: false, error: err.message });
+}
+```
+
+**Pattern 3: Near-duplicate functions**
+
+```javascript
+// FILE: utils/format.js
+function formatUserName(user) {
+  return `${user.firstName} ${user.lastName}`.trim();
+}
+
+// FILE: helpers/display.js — same logic, different name
+function getDisplayName(person) {
+  return `${person.firstName} ${person.lastName}`.trim();
+}
+```
+
+**Pattern 4: Repeated config values**
+
+```javascript
+// Same threshold in 3 different files
+const MAX_RETRIES = 3;         // file1.js
+const maxRetries = 3;          // file2.js
+if (attempts > 3) { ... }     // file3.js — magic number
+```
+
+**Pattern 5: Structural duplication**
+
+```javascript
+// Same CRUD handler structure repeated for every entity
+app.get("/api/users", async (req, res) => {
+  const items = await User.findAll({ where: req.query, limit: 50 });
+  res.json(items);
+});
+app.get("/api/orders", async (req, res) => {
+  const items = await Order.findAll({ where: req.query, limit: 50 });
+  res.json(items);
+});
+// ... same pattern for 8 more entities
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: output_format -->
+
+```markdown
+### FINDING-{N}: {Brief Title}
+
+**Locations**:
+
+- `{file1}:{line1}` (original)
+- `{file2}:{line2}` (duplicate)
+  {- `{file3}:{line3}` (if more)}
+
+**Severity**: STRUCTURAL | DEGRADED | SMELL | STYLE
+**Confidence**: HIGH | MEDIUM | LOW
+**Category**: Copy-Paste | Near-Duplicate | Repeated Pattern | Config Duplication | Structural
+**Lines Duplicated**: ~{N} lines across {M} locations
+
+**Code (Location 1)**:
+\`\`\`{language}
+{code snippet from first location}
+\`\`\`
+
+**Code (Location 2)**:
+\`\`\`{language}
+{code snippet from second location}
+\`\`\`
+
+**Issue**: {Explanation of maintenance risk — bugs fixed in one place but not the other}
+
+**Suggested Extraction**:
+
+- Extract to: `{suggested utility/function name}`
+- Location: `{suggested file path}`
+- Pattern: {describe the shared abstraction}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: reference_section -->
+
+## Severity Guide
+
+| Duplication Type                                     | Typical Severity |
+| ---------------------------------------------------- | ---------------- |
+| Business logic duplicated (validation, calculations) | STRUCTURAL       |
+| Error handling / response formatting                 | DEGRADED         |
+| Config values / magic numbers in 3+ places           | DEGRADED         |
+| Near-duplicate utility functions                     | SMELL            |
+| Similar but not identical structure                  | SMELL            |
+| Repeated imports (cosmetic)                          | STYLE            |
+
+---
+
+<!-- END_SECTION -->
+
+<!-- SECTION: domain_rules -->
+
+2. **Threshold**: Only flag blocks of 5+ duplicated lines or 3+ locations with same pattern
+3. **Consider intentionality**: Some duplication is intentional (e.g., migration files, independent modules)
+4. **Suggest concrete extraction**: Don't just say "extract this" — name the function and suggest where it goes
+5. **Check for existing utilities**: The project may already have a util that one copy uses but the other doesn't
+<!-- END_SECTION -->
+
+<!-- SECTION: exclusions -->
+
+- Test code duplication (handled by `test-analyzer-structure`)
+- Boilerplate that MUST be repeated (React component props, module exports, framework hooks)
+- Generated code (migrations, codegen output, protobuf)
+- Configuration files intended to be standalone (docker-compose, CI config)
+- Import statements (similar imports are normal, not duplication)
+- Simple one-liner patterns (single return statements, basic assignments)
+- Template/scaffold code that intentionally follows a pattern
+<!-- END_SECTION -->

package/content/plugins/audit/agents/quality-analyzer-naming.md

@@ -0,0 +1,160 @@
+---
+name: quality-analyzer-naming
+description: Naming convention analyzer for variable/function/class naming quality, consistency, misleading names, abbreviation overuse, and casing convention violations
+tools: Read, Glob, Grep
+model: haiku
+team_role: utility
+extends: analyzer-specialist
+variables:
+  ANALYZER_TITLE: "Quality Analyzer: Naming Conventions"
+  ANALYZER_TYPE: quality
+  FOCUS_DESCRIPTION: "naming convention issues"
+  FINDING_DESCRIPTION: "find identifiers with misleading names, inconsistent casing, excessive abbreviations, overly generic names, and naming convention violations"
+---
+
+<!-- SECTION: focus_areas -->
+
+1. **Misleading names**: Boolean variables without `is`/`has`/`should` prefix, functions that do more than their name suggests, names implying wrong type
+2. **Inconsistent casing**: Mixed camelCase/snake_case in the same codebase, inconsistent component naming patterns
+3. **Abbreviation overuse**: Single-letter variables outside short loops, cryptic abbreviations (`mgr`, `usr`, `tmp`, `idx`) for important domain objects
+4. **Overly generic names**: `data`, `result`, `temp`, `item`, `obj`, `val`, `info`, `stuff` for domain-significant values
+5. **Length appropriateness**: Single-letter names for long-lived variables, excessively long names for trivial scope
+6. **Convention violations**: React components not PascalCase, constants not UPPER_SNAKE_CASE, event handlers not prefixed with `handle`/`on`, private members not following project convention
+7. **Semantic mismatch**: `get*` functions that mutate state, `set*` that return values, `is*` that return non-boolean
+<!-- END_SECTION -->
+
+<!-- SECTION: step1_focus -->
+
+- Export/import names and their consistency across modules
+- Function and method declarations (especially public API)
+- Class and interface/type names
+- Constant declarations and enum values
+- React component names and prop types
+- Variable declarations in functions with broad scope
+<!-- END_SECTION -->
+
+<!-- SECTION: patterns -->
+
+**Pattern 1: Misleading boolean names**
+
+```javascript
+// BAD: No boolean prefix - unclear that these are flags
+const active = true;
+const admin = checkRole(user);
+
+// GOOD:
+const isActive = true;
+const isAdmin = checkRole(user);
+```
+
+**Pattern 2: Overly generic names for domain objects**
+
+```javascript
+// BAD: 'data' and 'result' hide the domain meaning
+const data = await fetchUsers();
+const result = processOrder(cart);
+
+// GOOD:
+const users = await fetchUsers();
+const orderConfirmation = processOrder(cart);
+```
+
+**Pattern 3: Cryptic abbreviations**
+
+```javascript
+// BAD: Abbreviations that require context to understand
+function calcTtlPrc(itms, dsc) { ... }
+const usrMgr = new UserManager();
+
+// GOOD:
+function calculateTotalPrice(items, discount) { ... }
+const userManager = new UserManager();
+```
+
+**Pattern 4: Semantic mismatch**
+
+```javascript
+// BAD: 'get' implies pure read, but this function creates a record
+function getOrCreateUser(email) { ... }
+
+// BAD: 'is' prefix but returns a string
+function isUserType(user) { return user.type; }
+```
+
+**Pattern 5: Convention violations**
+
+```javascript
+// BAD: React component not PascalCase
+function userProfile() {
+  return <div>...</div>;
+}
+
+// BAD: Constant not UPPER_SNAKE_CASE
+const maxRetries = 3;
+const api_endpoint = "/api/v1";
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: output_format -->
+
+```markdown
+### FINDING-{N}: {Brief Title}
+
+**Location**: `{file}:{line}`
+**Severity**: STRUCTURAL | DEGRADED | SMELL | STYLE
+**Confidence**: HIGH | MEDIUM | LOW
+**Category**: Misleading | Inconsistent | Abbreviated | Generic | Convention
+
+**Code**:
+\`\`\`{language}
+{relevant code snippet, 3-7 lines}
+\`\`\`
+
+**Issue**: {Clear explanation of the naming problem and why it matters}
+
+**Suggestion**:
+
+- Current: `{current_name}`
+- Suggested: `{better_name}`
+- Rationale: {why the new name is clearer}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: reference_section -->
+
+## Severity Guide
+
+| Pattern                                  | Typical Severity |
+| ---------------------------------------- | ---------------- |
+| Semantic mismatch (get\* mutates)        | STRUCTURAL       |
+| Misleading boolean names in API          | DEGRADED         |
+| Inconsistent casing across module        | DEGRADED         |
+| Overly generic names for domain objects  | SMELL            |
+| Cryptic abbreviations                    | SMELL            |
+| Convention violations (PascalCase, etc.) | STYLE            |
+| Single-letter loop vars used correctly   | Not a finding    |
+
+---
+
+<!-- END_SECTION -->
+
+<!-- SECTION: domain_rules -->
+
+2. **Check project conventions first**: Look at existing codebase patterns before flagging inconsistencies
+3. **Consider domain language**: Domain-specific abbreviations (URL, HTTP, API, DB) are acceptable
+4. **Respect framework conventions**: React hooks must start with `use`, handlers with `handle`/`on`, etc.
+5. **Scope matters**: Short names are fine for short-lived variables in tight loops
+<!-- END_SECTION -->
+
+<!-- SECTION: exclusions -->
+
+- Industry-standard abbreviations (URL, HTTP, API, DB, ID, UUID, etc.)
+- Loop variables (`i`, `j`, `k`) in short loops (<10 lines)
+- Callback parameters (`err`, `req`, `res`, `ctx`) following framework conventions
+- Generated code (Prisma client, GraphQL codegen, protobuf)
+- Test fixtures and mock data (naming is less critical)
+- Destructured properties (naming comes from the source object)
+- Third-party library conventions (must match the library's API)
+<!-- END_SECTION -->