agentic-forge 0.0.0

package/src/claude/.claude/skills/analyze/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: af-analyze
+description: Analyze codebase for bugs, debt, documentation, security, or style issues
+argument-hint: <type> [paths...]
+---
+
+# Analyze Codebase
+
+## Overview
+
+Analyze codebase for issues across multiple domains: bugs, technical debt, documentation, security vulnerabilities, or style inconsistencies. Categorizes findings by severity with specific file locations and actionable fix suggestions. Returns structured JSON for workflow integration and generates a markdown report.
+
+## Arguments
+
+### Definitions
+
+- **`<type>`** (required): Analysis type to perform. Must be one of:
+  - `bug` - Logic errors, runtime errors, and edge cases
+  - `debt` - Technical debt, architecture, and performance issues
+  - `doc` - Documentation accuracy and completeness
+  - `security` - Vulnerabilities, unsafe patterns, and dependency issues
+  - `style` - Code style, consistency, and best practices
+- **`[paths...]`** (optional): Space-separated list of files or directories to analyze. When provided, only these paths are analyzed. Otherwise, the entire codebase is analyzed.
+
+### Values
+
+\$ARGUMENTS
+
+## Additional Resources
+
+Load ONE of these based on the `<type>` argument:
+
+- For bug analysis, see [references/bug.md](references/bug.md)
+- For debt analysis, see [references/debt.md](references/debt.md)
+- For doc analysis, see [references/doc.md](references/doc.md)
+- For security analysis, see [references/security.md](references/security.md)
+- For style analysis, see [references/style.md](references/style.md)
+
+## Core Principles
+
+- Only report REAL issues - quality over quantity
+- Only report UNFIXED issues - if resolved, do not include it
+- Be specific with exact file and line numbers
+- Understand project patterns before flagging issues
+- Consider framework conventions and intentional design choices
+- Check if apparent issues are handled elsewhere before flagging
+- Recognize test-specific patterns and legitimate edge cases
+- If no issues found, return success with zero counts
+
+## Instructions
+
+1. **Validate Type Argument**
+   - Check that `<type>` argument is provided
+   - Verify it is one of: `bug`, `debt`, `doc`, `security`, `style`
+   - If missing or invalid, stop execution and return error:
+
+     ```json
+     {
+       "success": false,
+       "error": "Invalid or missing type argument. Must be one of: bug, debt, doc, security, style"
+     }
+     ```
+
+2. **Load Type-Specific Guidelines**
+   Based on the `<type>` argument, load the corresponding reference file:
+   - `bug` -> Read [references/bug.md](references/bug.md)
+   - `debt` -> Read [references/debt.md](references/debt.md)
+   - `doc` -> Read [references/doc.md](references/doc.md)
+   - `security` -> Read [references/security.md](references/security.md)
+   - `style` -> Read [references/style.md](references/style.md)
+
+3. **Determine Scope**
+   - If `[paths]` are provided, focus only on those files/directories
+   - Otherwise, analyze the entire codebase
+   - Exclude test files, node_modules, build outputs, and vendor directories
+   - For `doc` type: find all documentation files (README, docs/, \*.md)
+
+4. **Understand Project Context**
+   - Check for linter configs (ESLint, Prettier, Ruff)
+   - Read CLAUDE.md for project-specific guidelines
+   - Analyze existing code patterns to understand conventions
+
+5. **Analyze for Issues**
+   - Apply type-specific analysis criteria from the loaded reference file
+   - Verify each finding is a real issue, not a false positive
+   - Check if apparent issues are handled elsewhere
+
+6. **Categorize Findings**
+   Rate each finding by severity (all types use this scale):
+   - **Critical**: Severe impact - crashes, data loss, security breaches, misleading docs
+   - **High**: Significant impact - functional bugs, major gaps, exploitable with conditions
+   - **Medium**: Moderate impact - edge cases, minor issues, incomplete coverage
+   - **Low**: Minimal impact - best practice violations, minor improvements
+
+7. **Generate Report**
+   - Save to `agentic/analysis/<type>.md`
+   - Include date in report header
+   - Group findings by severity
+
+8. **Return JSON Output**
+   - Return structured JSON matching the output schema
+   - Use the unified finding schema for all types
+   - Include notes only when meaningful (see type-specific reference for guidance)
+
+## Output Guidance
+
+Return a JSON object AND save a detailed markdown report.
+
+### JSON Output Schema
+
+```json
+{
+  "success": true,
+  "analysis_type": "{{type}}",
+  "findings_count": {
+    "critical": "{{critical_count}}",
+    "high": "{{high_count}}",
+    "medium": "{{medium_count}}",
+    "low": "{{low_count}}",
+    "total": "{{total_count}}"
+  },
+  "findings": ["{{findings_array}}"],
+  "document_path": "agentic/analysis/{{type}}.md"
+}
+```
+
+<!--
+Placeholders:
+- {{type}}: Analysis type (bug, debt, doc, security, style)
+- {{critical_count}}, {{high_count}}, {{medium_count}}, {{low_count}}: Integer counts per severity
+- {{total_count}}: Sum of all findings
+- {{findings_array}}: Array of finding objects using the Finding Schema below
+-->
+
+### Finding Schema
+
+All analysis types use this unified finding structure:
+
+```json
+{
+  "id": "{{id_prefix}}-{{sequence}}",
+  "severity": "{{severity}}",
+  "title": "{{title}}",
+  "file": "{{file}}",
+  "line": "{{line}}",
+  "description": "{{description}}",
+  "fix": "{{fix}}",
+  "notes": "{{notes}}"
+}
+```
+
+<!--
+Placeholders:
+- {{id_prefix}}: Type-based prefix (BUG, DEBT, DOC, SEC, STYLE)
+- {{sequence}}: Sequential number starting at 001
+- {{severity}}: One of critical, high, medium, low
+- {{title}}: Brief descriptive title of the issue
+- {{file}}: Path to the affected file
+- {{line}}: Line number where issue occurs
+- {{description}}: What is wrong and why it's a problem
+- {{fix}}: How to fix the issue
+- {{notes}}: Optional additional context (omit key if empty)
+
+ID Prefixes by type:
+- bug -> BUG-001, BUG-002, ...
+- debt -> DEBT-001, DEBT-002, ...
+- doc -> DOC-001, DOC-002, ...
+- security -> SEC-001, SEC-002, ...
+- style -> STYLE-001, STYLE-002, ...
+
+Notes field: Optional. Only include when there is meaningful additional context.
+See the type-specific reference file for guidance on what to include.
+-->
+
+## Templates
+
+### Markdown Report Template
+
+Save to `agentic/analysis/<type>.md`:
+
+```markdown
+# {{type_title}} Analysis Report
+
+**Date**: {{date}}
+**Scope**: {{scope}}
+
+## Summary
+
+| Severity | Count              |
+| -------- | ------------------ |
+| Critical | {{critical_count}} |
+| High     | {{high_count}}     |
+| Medium   | {{medium_count}}   |
+| Low      | {{low_count}}      |
+
+## Critical
+
+### {{id}}: {{title}}
+
+**File:** {{file}}
+**Line:** {{line}}
+**Description:** {{description}}
+**Fix:** {{fix}}
+**Notes:** {{notes}}
+
+---
+
+## High
+
+[Repeat finding format for each high severity issue]
+
+## Medium
+
+[Repeat finding format for each medium severity issue]
+
+## Low
+
+[Repeat finding format for each low severity issue]
+```
+
+<!--
+Placeholders:
+- {{type}}: Analysis type in lowercase (bug, debt, doc, security, style)
+- {{type_title}}: Analysis type capitalized for title (Bug, Debt, Doc, Security, Style)
+- {{date}}: Current date in YYYY-MM-DD format
+- {{scope}}: "Entire codebase" or comma-separated list of analyzed paths
+- {{critical_count}}, {{high_count}}, {{medium_count}}, {{low_count}}: Integer counts
+- {{id}}: Finding ID with prefix (e.g., BUG-001, SEC-003)
+- {{title}}: Brief descriptive title
+- {{file}}: Path to the affected file
+- {{line}}: Line number where issue occurs
+- {{description}}: What is wrong and why it's a problem
+- {{fix}}: How to fix the issue
+- {{notes}}: Optional additional context (omit line if empty)
+
+Structure:
+- Group findings by severity section (Critical, High, Medium, Low)
+- Within each section, list findings in ID order
+- Add horizontal rule (---) between findings
+- Omit empty severity sections
+-->

package/src/claude/.claude/skills/analyze/references/bug.md

@@ -0,0 +1,62 @@
+# Bug Analysis Reference
+
+## Analysis Criteria
+
+Focus on finding real bugs, not theoretical concerns:
+
+**Logic Errors:**
+
+- Incorrect conditions, off-by-one errors, wrong operators
+- Inverted boolean logic, missing negations
+- Incorrect loop bounds or termination conditions
+
+**Runtime Errors:**
+
+- Null/undefined access without guards
+- Type mismatches and coercion issues
+- Uninitialized variables, use before assignment
+- Array index out of bounds
+
+**Error Handling:**
+
+- Unhandled exceptions, missing catch blocks
+- Silent failures that swallow errors
+- Missing error cases in switch/if chains
+- Promises without rejection handling
+
+**Race Conditions:**
+
+- Async timing issues, state corruption
+- Shared state modifications without synchronization
+- Deadlocks and livelocks
+- Check-then-act patterns without atomicity
+
+**Resource Leaks:**
+
+- Unclosed file handles, streams, connections
+- Memory leaks from retained references
+- Connection pool exhaustion
+- Event listener accumulation
+
+**Edge Cases:**
+
+- Boundary conditions (empty, max, min values)
+- Empty inputs, null collections
+- Overflow/underflow scenarios
+- Unicode and encoding edge cases
+
+## Severity Guidelines
+
+- **Critical**: Will cause crashes, data loss, or security issues in normal operation
+- **High**: Significant functional bugs affecting users under common conditions
+- **Medium**: Edge case bugs, minor functional issues, rare conditions
+- **Low**: Potential issues, defensive improvements, unlikely scenarios
+
+## Notes
+
+Include in the `notes` field when relevant:
+
+- Steps to reproduce the bug
+- Related code paths that may also be affected
+- Workarounds currently in place
+- Test cases that would catch this bug

package/src/claude/.claude/skills/analyze/references/debt.md

@@ -0,0 +1,76 @@
+# Debt Analysis Reference
+
+## Analysis Criteria
+
+Look for technical debt that provides real improvement value. Working code has value - perfect is the enemy of good.
+
+### Architecture
+
+- Circular dependencies between modules
+- Overly complex module structures
+- Missing abstraction layers where patterns repeat
+- Tight coupling between components that should be independent
+- God objects/classes that do too much
+
+### Code Quality
+
+- Significant code duplication (not trivial repetition)
+- Complex functions with high cyclomatic complexity
+- Long methods/classes that should be split
+- Poor naming that obscures intent
+- Magic numbers/strings without explanation
+
+### Patterns
+
+- Outdated patterns (callbacks vs async/await)
+- Inconsistent patterns across the codebase
+- Anti-patterns (singletons abuse, global state, etc.)
+- Framework misuse or fighting the framework
+
+### Performance
+
+- Obvious performance bottlenecks
+- N+1 query patterns in database access
+- Unnecessary re-renders in UI frameworks
+- Missing caching opportunities for expensive operations
+- Synchronous operations that should be async
+
+## Effort Estimation
+
+**Low Effort:**
+
+- Simple refactoring
+- Renaming for clarity
+- Extracting small functions
+- Adding types/documentation
+
+**Medium Effort:**
+
+- Extracting modules/classes
+- Refactoring patterns
+- Adding caching
+- Query optimization
+
+**High Effort:**
+
+- Architectural changes
+- Major refactoring
+- Database schema changes
+- API redesign
+
+## Severity Guidelines
+
+- **Critical**: Blocking further development or causing cascading issues
+- **High**: Significant maintainability burden, frequently touched code
+- **Medium**: Noticeable friction, moderate impact areas
+- **Low**: Minor improvements, rarely touched code
+
+## Notes
+
+Include in the `notes` field when relevant:
+
+- Category: architecture, code_quality, patterns, or performance
+- Effort estimate: low, medium, or high
+- Benefit of fixing (why it matters)
+- Dependencies on other debt items
+- Suggested refactoring approach

package/src/claude/.claude/skills/analyze/references/doc.md

@@ -0,0 +1,67 @@
+# Documentation Analysis Reference
+
+## Analysis Criteria
+
+Check documentation against actual code. Verify claims before marking as incorrect.
+
+### Outdated Information
+
+- Does not match current code behavior
+- References removed features or APIs
+- Uses deprecated patterns or syntax
+
+### Incorrect Content
+
+- Factually wrong statements
+- Wrong API signatures or parameters
+- Incorrect behavior descriptions
+- Security-related misinformation
+
+### Missing Documentation
+
+- Undocumented public APIs
+- Missing feature documentation
+- No setup/installation instructions
+- Missing configuration options
+
+### Broken References
+
+- Dead links (internal and external)
+- Invalid file paths
+- References to non-existent sections
+
+### Inconsistencies
+
+- Contradictory information across files
+- Different explanations for same concept
+- Version mismatches
+
+### Incomplete Examples
+
+- Non-working code samples
+- Examples missing required imports
+- Outdated syntax in examples
+
+## Verification Process
+
+1. Compare API documentation with actual implementations
+2. Check if documented features exist
+3. Verify code examples compile/run
+4. Ensure types match documented signatures
+5. Consider documentation may be ahead of code (planned features)
+
+## Severity Guidelines
+
+- **Critical**: Wrong or misleading - will confuse/mislead users, security misinformation
+- **High**: Outdated or incomplete - significant gaps, missing important sections
+- **Medium**: Moderate issues - outdated examples, unclear explanations
+- **Low**: Minor improvements - typos, grammar, organization suggestions
+
+## Notes
+
+Include in the `notes` field when relevant:
+
+- Code reference: the source file that contradicts the documentation
+- Additional files affected by the same issue
+- Whether documentation might be ahead of code (planned feature)
+- Correct information that should replace the incorrect content

package/src/claude/.claude/skills/analyze/references/security.md

@@ -0,0 +1,76 @@
+# Security Analysis Reference
+
+## Analysis Criteria
+
+Check for common security issues. Verify exploitability before reporting critical/high severity. This complements but does not replace SAST tools and security audits.
+
+### Injection
+
+- **SQL Injection**: Unsanitized input in SQL queries
+- **Command Injection**: User input passed to shell commands
+- **XSS**: Unescaped output in HTML/JavaScript contexts
+- **Template Injection**: User input in template engines
+- **Path Traversal**: Unsanitized file paths
+
+### Authentication/Authorization
+
+- Hardcoded credentials in source code
+- Weak authentication mechanisms
+- Missing authorization checks on endpoints
+- Session management issues (fixation, hijacking)
+- Insecure token storage (localStorage for sensitive data)
+- Missing CSRF protection
+
+### Data Exposure
+
+- Sensitive data in logs (passwords, tokens, PII)
+- Secrets in code or config files
+- Insecure data transmission (HTTP for sensitive data)
+- Verbose error messages revealing internals
+- Debug endpoints exposed in production
+
+### Dependencies
+
+- Known vulnerable packages (check CVE databases)
+- Outdated dependencies with security fixes
+- Unused but risky dependencies
+
+### Configuration
+
+- Debug mode enabled in production
+- Insecure defaults (weak passwords, open permissions)
+- Missing security headers (CSP, HSTS, X-Frame-Options)
+- CORS misconfigurations (overly permissive origins)
+- Exposed admin interfaces
+
+## OWASP Top 10 Reference
+
+| Category                           | What to Check                                    |
+| ---------------------------------- | ------------------------------------------------ |
+| A01:2021 Broken Access Control     | Missing auth checks, IDOR, path traversal        |
+| A02:2021 Cryptographic Failures    | Weak crypto, hardcoded secrets, insecure storage |
+| A03:2021 Injection                 | SQL, command, XSS, template injection            |
+| A04:2021 Insecure Design           | Logic flaws, missing security requirements       |
+| A05:2021 Security Misconfiguration | Debug mode, default creds, exposed configs       |
+| A06:2021 Vulnerable Components     | Outdated deps, known CVEs                        |
+| A07:2021 Auth Failures             | Weak auth, session issues, credential stuffing   |
+| A08:2021 Data Integrity Failures   | Insecure deserialization, unsigned data          |
+| A09:2021 Logging Failures          | Missing logs, sensitive data in logs             |
+| A10:2021 SSRF                      | Server-side request forgery                      |
+
+## Severity Guidelines
+
+- **Critical**: Actively exploitable, high impact (RCE, data breach, auth bypass)
+- **High**: Exploitable with some conditions, significant impact
+- **Medium**: Potential risk, limited impact, requires specific conditions
+- **Low**: Best practice violation, minimal direct risk
+
+## Notes
+
+Include in the `notes` field when relevant:
+
+- Vulnerability type with CWE ID (e.g., "SQL Injection (CWE-89)")
+- Risk assessment: what could happen if exploited
+- OWASP category reference
+- Attack vector or exploitation scenario
+- Related vulnerabilities in the same flow

package/src/claude/.claude/skills/analyze/references/style.md

@@ -0,0 +1,72 @@
+# Style Analysis Reference
+
+## Analysis Criteria
+
+Focus on normalization - there should be ONE way of doing things. Majority pattern wins - align outliers to dominant pattern. Respect existing patterns and work with the codebase, not against it.
+
+### Naming
+
+- Inconsistent naming conventions across files
+- Mixed camelCase/snake_case within same context
+- Inconsistent abbreviations (btn vs button, msg vs message)
+- Non-descriptive names that obscure intent
+
+### Patterns
+
+- Different ways of handling the same thing
+- Inconsistent error handling patterns
+- Mixed async patterns (callbacks vs promises vs async/await)
+- Inconsistent component patterns in UI code
+- Different state management approaches
+
+### Structure
+
+- Inconsistent file organization
+- Mixed import styles (default vs named, relative vs absolute)
+- Inconsistent export patterns (named vs default vs barrel)
+- Module organization inconsistencies
+
+### Formatting
+
+- Issues not caught by automated formatters
+- Inconsistent whitespace in logic blocks
+- Comment style inconsistencies
+- Inconsistent brace/bracket placement
+
+## Pattern Detection Tables
+
+### Naming Conventions
+
+| Pattern    | Variations to Detect                                |
+| ---------- | --------------------------------------------------- |
+| Functions  | `getUserData` vs `get_user_data` vs `GetUserData`   |
+| Variables  | `isLoading` vs `loading` vs `is_loading`            |
+| Constants  | `MAX_RETRIES` vs `maxRetries` vs `MaxRetries`       |
+| Components | `UserCard` vs `userCard` vs `User_Card`             |
+| Files      | `UserCard.tsx` vs `user-card.tsx` vs `userCard.tsx` |
+
+### Code Patterns
+
+| Area           | Variations to Detect                      |
+| -------------- | ----------------------------------------- |
+| Error handling | try/catch vs .catch() vs error boundaries |
+| Async          | async/await vs .then() vs callbacks       |
+| State updates  | setState vs reducer vs signals            |
+| Props          | destructuring vs props.x                  |
+| Exports        | named vs default vs barrel files          |
+
+## Severity Guidelines
+
+- **Critical**: Fundamental inconsistencies that significantly harm readability
+- **High**: Major deviations from established patterns in key areas
+- **Medium**: Noticeable inconsistencies that create friction
+- **Low**: Minor style variations, cosmetic issues
+
+## Notes
+
+Include in the `notes` field when relevant:
+
+- The established project standard for this pattern
+- Count of files following majority pattern vs outliers
+- Whether this is a naming, pattern, structure, or formatting issue
+- Other files with the same inconsistency

package/src/claude/.claude/skills/create-checkpoint/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: af-create-checkpoint
+description: Create a checkpoint to track progress and share context
+argument-hint: <workflow-id> <step> <status> <context>
+---
+
+# Create Checkpoint
+
+## Overview
+
+Record progress and provide context for future sessions or other agents. Use this skill when completing milestones, handing off work, encountering issues, or reaching natural pause points. Creates a checkpoint entry that captures the current workflow state for resumption or handoff.
+
+## Arguments
+
+### Definitions
+
+- **`<workflow-id>`** (required): The workflow identifier for output organization.
+- **`<step>`** (required): Current step name (e.g., analyze, plan, review).
+- **`<status>`** (required): Checkpoint status. Values: `in_progress`, `completed`.
+- **`<context>`** (required): Summary of current situation and progress.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- Checkpoints are append-only within a workflow
+- Include enough context for seamless resumption
+- Note any blockers or issues discovered
+- Track progress with markdown checklists
+
+## Instructions
+
+1. Parse the workflow-id, step name, and status
+2. Generate checkpoint ID (chk-NNN)
+3. Create checkpoint entry with:
+   - Context summary
+   - Progress checklist
+   - Notes for next session
+   - Issues discovered
+4. Save to `agentic/outputs/{workflow-id}/checkpoint.md`
+5. Return confirmation with checkpoint ID
+
+## Output Guidance
+
+Return JSON confirmation:
+
+```json
+{
+  "success": true,
+  "checkpoint_id": "chk-001",
+  "workflow_id": "abc123"
+}
+```
+
+## Templates
+
+### Checkpoint File Format
+
+Checkpoints are stored in `agentic/outputs/{workflow-id}/checkpoint.md`:
+
+```markdown
+---
+checkpoint_id: chk-001
+step: build
+created: 2024-01-15T14:30:00Z
+workflow_id: abc-123
+status: in_progress
+---
+
+## Context
+
+Summary of the current situation...
+
+## Progress
+
+- [x] Completed task
+- [ ] Pending task
+
+## Notes for Next Session
+
+Important details...
+
+## Issues Discovered
+
+Problems found...
+```