ac-framework 1.5.0 → 1.6.0

package/framework/.clinerules/skills/secure-coding-cybersecurity/references/ai_coding_pitfalls.md

@@ -0,0 +1,44 @@
+# AI-Generated Code: Security Pitfalls & Anti-Patterns
+
+This document lists the most common security errors made by LLMs when generating code. As an AI agent, you **MUST AVOID** these patterns and explicitly check for them in your output.
+
+## 1. The "Working but Insecure" Default
+LLMs prioritize functionality over security. They often provide the simplest code that works, which is usually the least secure.
+- **NEVER** skip input validation because it "makes the example cleaner."
+- **NEVER** use `http` when `https` is available.
+- **NEVER** disable SSL/TLS certificate verification for "easier testing."
+
+## 2. Dependency Hallucinations & Slopsquatting
+LLMs may suggest non-existent libraries or versions.
+- **NEVER** suggest a library without verifying its existence and reputation.
+- **BEWARE** of "slopsquatting": attackers registering hallucinated package names with malicious code.
+- **ALWAYS** prefer well-known, standard libraries over obscure ones suggested by the model.
+
+## 3. Stale & Outdated Security Patterns
+LLMs are trained on historical data and often suggest patterns that were "okay" years ago but are now insecure.
+- **DO NOT** use `MD5` or `SHA1` for password hashing; use `Argon2` or `bcrypt`.
+- **DO NOT** use `random.random()` for security-sensitive tokens; use `secrets` module in Python or `crypto.getRandomValues()` in JS.
+- **DO NOT** use deprecated APIs (e.g., `os.system()` when `subprocess.run()` with proper arguments is safer).
+
+## 4. Hardcoded Secrets & Debug Flags
+To make code "run out of the box," LLMs often hardcode sensitive values.
+- **NEVER** include hardcoded API keys, passwords, or tokens. Use environment variables.
+- **NEVER** leave `debug=True` or verbose error reporting enabled in "production-ready" snippets.
+
+## 5. Missing Contextual Security
+LLMs often miss the "big picture" of an application's security.
+- **DO NOT** assume authentication happened elsewhere. Always verify authorization at the function/endpoint level.
+- **DO NOT** suggest CORS configurations like `Access-Control-Allow-Origin: *` unless explicitly required and justified.
+
+## 6. Injection Vulnerabilities (The Most Common Error)
+LLMs frequently fall back to string concatenation for queries and commands.
+- **NEVER** use f-strings or string formatting for SQL queries. Use parameterized inputs.
+- **NEVER** pass unsanitized user input directly to shell commands.
+
+## AI Security Checklist (Before Delivering Code)
+1. [ ] Did I use any hallucinated or obscure libraries?
+2. [ ] Are all inputs validated and sanitized?
+3. [ ] Did I use the most modern, secure cryptographic standards?
+4. [ ] Are there any hardcoded secrets or debug flags?
+5. [ ] Does the code "fail closed" on errors?
+6. [ ] Did I verify permissions at the point of data access?

package/framework/.clinerules/skills/secure-coding-cybersecurity/references/owasp_top_10_2025.md

@@ -0,0 +1,28 @@
+# OWASP Top 10:2025 Reference
+
+The OWASP Top 10 is the standard awareness document for developers and web application security. It represents a broad consensus about the most critical security risks to web applications.
+
+| ID | Name | Description | Key Prevention |
+| :--- | :--- | :--- | :--- |
+| **A01:2025** | **Broken Access Control** | Users can act outside of their intended permissions. | Implement least privilege; check permissions on every request. |
+| **A02:2025** | **Security Misconfiguration** | Insecure default settings, incomplete configurations, or open cloud storage. | Automate hardening; remove unused features/debug modes. |
+| **A03:2025** | **Software Supply Chain Failures** | Risks from third-party libraries, dependencies, and CI/CD pipelines. | Use SBOMs; verify signatures; use dependency scanning (SCA). |
+| **A04:2025** | **Cryptographic Failures** | Use of weak or no encryption for sensitive data. | Use strong algorithms (Argon2, AES-GCM); encrypt data at rest/transit. |
+| **A05:2025** | **Injection** | Malicious data sent to an interpreter (SQL, NoSQL, OS Command). | Use parameterized queries; validate and sanitize all inputs. |
+| **A06:2025** | **Insecure Design** | Flaws in the application's architecture and design. | Use secure design patterns; perform threat modeling early. |
+| **A07:2025** | **Authentication Failures** | Weaknesses in identity verification, session management, or password policies. | Implement MFA; use secure session managers; enforce strong passwords. |
+| **A08:2025** | **Software and Data Integrity Failures** | Insecure deserialization or lack of integrity checks on updates/data. | Sign code/data; verify integrity before processing; avoid insecure deserialization. |
+| **A09:2025** | **Security Logging & Alerting Failures** | Insufficient logging or monitoring to detect and respond to active attacks. | Log security events; implement real-time alerting; centralize logs. |
+| **A10:2025** | **Mishandling of Exceptional Conditions** | Improper error handling, failing open, or leaking info via error messages. | Fail closed; use generic error messages; handle all exceptions. |
+
+## Deep Dive: New/Updated Categories
+
+### A03:2025 Software Supply Chain Failures
+This category focuses on the risks associated with the components and services that make up the software development life cycle.
+- **Vulnerabilities**: Using libraries with known vulnerabilities (CVEs), dependency confusion attacks, compromised build pipelines.
+- **Prevention**: Generate and maintain a **Software Bill of Materials (SBOM)**, use tools like `npm audit`, `pip-audit`, or Snyk.
+
+### A10:2025 Mishandling of Exceptional Conditions
+Focuses on how the application behaves when things go wrong.
+- **Vulnerabilities**: "Fail-open" logic (e.g., if an auth check throws an error, it defaults to 'allow'), leaking stack traces or sensitive environment variables in error responses.
+- **Prevention**: Always "Fail-closed". Ensure that if an error occurs during a security check, access is denied by default.

package/framework/.clinerules/skills/secure-coding-cybersecurity/references/secure_coding_examples.md

@@ -0,0 +1,102 @@
+# Secure Coding Examples
+
+This document provides comparisons between vulnerable and secure code across multiple languages.
+
+## 1. Injection (A05:2025) - SQL Injection
+
+### Python (Insecure)
+```python
+# VULNERABLE: String formatting allows SQL injection
+cursor.execute(f"SELECT * FROM users WHERE username = '{username}'")
+```
+
+### Python (Secure)
+```python
+# SECURE: Use parameterized queries
+cursor.execute("SELECT * FROM users WHERE username = %s", (username,))
+```
+
+### Node.js (Secure)
+```javascript
+// SECURE: Using placeholders in pg-promise or similar
+db.any('SELECT * FROM users WHERE username = $1', [username]);
+```
+
+---
+
+## 2. Broken Access Control (A01:2025) - IDOR
+
+### Node.js (Insecure)
+```javascript
+// VULNERABLE: No check if the user owns the record
+app.get('/api/invoice/:id', async (req, res) => {
+    const invoice = await db.getInvoice(req.params.id);
+    res.json(invoice);
+});
+```
+
+### Node.js (Secure)
+```javascript
+// SECURE: Verify ownership
+app.get('/api/invoice/:id', async (req, res) => {
+    const invoice = await db.getInvoice(req.params.id);
+    if (invoice.userId !== req.user.id) {
+        return res.status(403).send('Forbidden');
+    }
+    res.json(invoice);
+});
+```
+
+---
+
+## 3. Cryptographic Failures (A04:2025) - Password Hashing
+
+### Python (Secure)
+```python
+import argon2
+
+ph = argon2.PasswordHasher()
+hash = ph.hash("my_secure_password")
+# To verify:
+ph.verify(hash, "user_input_password")
+```
+
+---
+
+## 4. Mishandling of Exceptional Conditions (A10:2025) - Fail Closed
+
+### Java (Insecure)
+```java
+// VULNERABLE: Fail-open logic
+public boolean isAuthorized(User user) {
+    try {
+        return ldapService.checkAccess(user);
+    } catch (Exception e) {
+        // If service is down, it might return true or allow bypass
+        return true; 
+    }
+}
+```
+
+### Java (Secure)
+```java
+// SECURE: Fail-closed logic
+public boolean isAuthorized(User user) {
+    try {
+        return ldapService.checkAccess(user);
+    } catch (Exception e) {
+        logger.error("Auth service error", e);
+        return false; // Access denied by default
+    }
+}
+```
+
+---
+
+## 5. Software Supply Chain (A03:2025) - Dependency Management
+
+### Best Practices
+- **Python**: Use `pip-audit` to check for known vulnerabilities.
+- **Node.js**: Use `npm audit` or `pnpm audit`.
+- **General**: Use a Lockfile (`package-lock.json`, `poetry.lock`) to ensure consistent builds.
+- **SBOM**: Generate an SBOM using tools like `syft` or `cyclonedx-cli`.

package/framework/.clinerules/skills/secure-coding-cybersecurity/scripts/security_audit.py

@@ -0,0 +1,46 @@
+import re
+import os
+import sys
+
+# Common patterns for hardcoded secrets and vulnerable code
+PATTERNS = {
+    "Hardcoded Secret": r"(?i)(api_key|secret|password|token|access_key)\s*=\s*['\"][a-zA-Z0-9_\-]{10,}['\"]",
+    "Potential SQL Injection (Python)": r"\.execute\(f?['\"].*\{.*\}",
+    "Insecure Randomness": r"import random\s+.*random\.random\(",
+    "Weak Hashing (MD5/SHA1)": r"(md5|sha1)\(",
+    "Debug Mode Enabled": r"debug\s*=\s*True",
+}
+
+def scan_file(file_path):
+    findings = []
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            for i, line in enumerate(f, 1):
+                for name, pattern in PATTERNS.items():
+                    if re.search(pattern, line):
+                        findings.append(f"[{name}] Found at line {i}: {line.strip()}")
+    except Exception as e:
+        print(f"Error reading {file_path}: {e}")
+    return findings
+
+def main(directory):
+    all_findings = {}
+    for root, _, files in os.walk(directory):
+        for file in files:
+            if file.endswith(('.py', '.js', '.java', '.go')):
+                path = os.path.join(root, file)
+                findings = scan_file(path)
+                if findings:
+                    all_findings[path] = findings
+    
+    if not all_findings:
+        print("No obvious security issues found by this simple scanner.")
+    else:
+        for path, findings in all_findings.items():
+            print(f"\n--- Findings in {path} ---")
+            for f in findings:
+                print(f)
+
+if __name__ == "__main__":
+    target_dir = sys.argv[1] if len(sys.argv) > 1 else "."
+    main(target_dir)

package/framework/.clinerules/skills/skill-writer/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: skill-writer
+description: Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
+---
+
+# Skill Writer
+
+This Skill helps you create well-structured Agent Skills for Claude Code that follow best practices and validation requirements.
+
+## When to use this Skill
+
+Use this Skill when:
+- Creating a new Agent Skill
+- Writing or updating SKILL.md files
+- Designing skill structure and frontmatter
+- Troubleshooting skill discovery issues
+- Converting existing prompts or workflows into Skills
+
+## Instructions
+
+### Step 1: Determine Skill scope
+
+First, understand what the Skill should do:
+
+1. **Ask clarifying questions**:
+   - What specific capability should this Skill provide?
+   - When should Claude use this Skill?
+   - What tools or resources does it need?
+   - Is this for personal use or team sharing?
+
+2. **Keep it focused**: One Skill = one capability
+   - Good: "PDF form filling", "Excel data analysis"
+   - Too broad: "Document processing", "Data tools"
+
+### Step 2: Choose Skill location
+
+Determine where to create the Skill:
+
+**Personal Skills** (`~/.claude/skills/`):
+- Individual workflows and preferences
+- Experimental Skills
+- Personal productivity tools
+
+**Project Skills** (`.claude/skills/`):
+- Team workflows and conventions
+- Project-specific expertise
+- Shared utilities (committed to git)
+
+### Step 3: Create Skill structure
+
+Create the directory and files:
+
+```bash
+# Personal
+mkdir -p ~/.claude/skills/skill-name
+
+# Project
+mkdir -p .claude/skills/skill-name
+```
+
+For multi-file Skills:
+```
+skill-name/
+├── SKILL.md (required)
+├── reference.md (optional)
+├── examples.md (optional)
+├── scripts/
+│   └── helper.py (optional)
+└── templates/
+    └── template.txt (optional)
+```
+
+### Step 4: Write SKILL.md frontmatter
+
+Create YAML frontmatter with required fields:
+
+```yaml
+---
+name: skill-name
+description: Brief description of what this does and when to use it
+---
+```
+
+**Field requirements**:
+
+- **name**:
+  - Lowercase letters, numbers, hyphens only
+  - Max 64 characters
+  - Must match directory name
+  - Good: `pdf-processor`, `git-commit-helper`
+  - Bad: `PDF_Processor`, `Git Commits!`
+
+- **description**:
+  - Max 1024 characters
+  - Include BOTH what it does AND when to use it
+  - Use specific trigger words users would say
+  - Mention file types, operations, and context
+
+**Optional frontmatter fields**:
+
+- **allowed-tools**: Restrict tool access (comma-separated list)
+  ```yaml
+  allowed-tools: Read, Grep, Glob
+  ```
+  Use for:
+  - Read-only Skills
+  - Security-sensitive workflows
+  - Limited-scope operations
+
+### Step 5: Write effective descriptions
+
+The description is critical for Claude to discover your Skill.
+
+**Formula**: `[What it does] + [When to use it] + [Key triggers]`
+
+**Examples**:
+
+✅ **Good**:
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+✅ **Good**:
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
+```
+
+❌ **Too vague**:
+```yaml
+description: Helps with documents
+description: For data analysis
+```
+
+**Tips**:
+- Include specific file extensions (.pdf, .xlsx, .json)
+- Mention common user phrases ("analyze", "extract", "generate")
+- List concrete operations (not generic verbs)
+- Add context clues ("Use when...", "For...")
+
+### Step 6: Structure the Skill content
+
+Use clear Markdown sections:
+
+```markdown
+# Skill Name
+
+Brief overview of what this Skill does.
+
+## Quick start
+
+Provide a simple example to get started immediately.
+
+## Instructions
+
+Step-by-step guidance for Claude:
+1. First step with clear action
+2. Second step with expected outcome
+3. Handle edge cases
+
+## Examples
+
+Show concrete usage examples with code or commands.
+
+## Best practices
+
+- Key conventions to follow
+- Common pitfalls to avoid
+- When to use vs. not use
+
+## Requirements
+
+List any dependencies or prerequisites:
+```bash
+pip install package-name
+```
+
+## Advanced usage
+
+For complex scenarios, see [reference.md](reference.md).
+```
+
+### Step 7: Add supporting files (optional)
+
+Create additional files for progressive disclosure:
+
+**reference.md**: Detailed API docs, advanced options
+**examples.md**: Extended examples and use cases
+**scripts/**: Helper scripts and utilities
+**templates/**: File templates or boilerplate
+
+Reference them from SKILL.md:
+```markdown
+For advanced usage, see [reference.md](reference.md).
+
+Run the helper script:
+\`\`\`bash
+python scripts/helper.py input.txt
+\`\`\`
+```
+
+### Step 8: Validate the Skill
+
+Check these requirements:
+
+✅ **File structure**:
+- [ ] SKILL.md exists in correct location
+- [ ] Directory name matches frontmatter `name`
+
+✅ **YAML frontmatter**:
+- [ ] Opening `---` on line 1
+- [ ] Closing `---` before content
+- [ ] Valid YAML (no tabs, correct indentation)
+- [ ] `name` follows naming rules
+- [ ] `description` is specific and < 1024 chars
+
+✅ **Content quality**:
+- [ ] Clear instructions for Claude
+- [ ] Concrete examples provided
+- [ ] Edge cases handled
+- [ ] Dependencies listed (if any)
+
+✅ **Testing**:
+- [ ] Description matches user questions
+- [ ] Skill activates on relevant queries
+- [ ] Instructions are clear and actionable
+
+### Step 9: Test the Skill
+
+1. **Restart Claude Code** (if running) to load the Skill
+
+2. **Ask relevant questions** that match the description:
+   ```
+   Can you help me extract text from this PDF?
+   ```
+
+3. **Verify activation**: Claude should use the Skill automatically
+
+4. **Check behavior**: Confirm Claude follows the instructions correctly
+
+### Step 10: Debug if needed
+
+If Claude doesn't use the Skill:
+
+1. **Make description more specific**:
+   - Add trigger words
+   - Include file types
+   - Mention common user phrases
+
+2. **Check file location**:
+   ```bash
+   ls ~/.claude/skills/skill-name/SKILL.md
+   ls .claude/skills/skill-name/SKILL.md
+   ```
+
+3. **Validate YAML**:
+   ```bash
+   cat SKILL.md | head -n 10
+   ```
+
+4. **Run debug mode**:
+   ```bash
+   claude --debug
+   ```
+
+## Common patterns
+
+### Read-only Skill
+
+```yaml
+---
+name: code-reader
+description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation.
+allowed-tools: Read, Grep, Glob
+---
+```
+
+### Script-based Skill
+
+```yaml
+---
+name: data-processor
+description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.
+---
+
+# Data Processor
+
+## Instructions
+
+1. Use the processing script:
+\`\`\`bash
+python scripts/process.py input.csv --output results.json
+\`\`\`
+
+2. Validate output with:
+\`\`\`bash
+python scripts/validate.py results.json
+\`\`\`
+```
+
+### Multi-file Skill with progressive disclosure
+
+```yaml
+---
+name: api-designer
+description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.
+---
+
+# API Designer
+
+Quick start: See [examples.md](examples.md)
+
+Detailed reference: See [reference.md](reference.md)
+
+## Instructions
+
+1. Gather requirements
+2. Design endpoints (see examples.md)
+3. Document with OpenAPI spec
+4. Review against best practices (see reference.md)
+```
+
+## Best practices for Skill authors
+
+1. **One Skill, one purpose**: Don't create mega-Skills
+2. **Specific descriptions**: Include trigger words users will say
+3. **Clear instructions**: Write for Claude, not humans
+4. **Concrete examples**: Show real code, not pseudocode
+5. **List dependencies**: Mention required packages in description
+6. **Test with teammates**: Verify activation and clarity
+7. **Version your Skills**: Document changes in content
+8. **Use progressive disclosure**: Put advanced details in separate files
+
+## Validation checklist
+
+Before finalizing a Skill, verify:
+
+- [ ] Name is lowercase, hyphens only, max 64 chars
+- [ ] Description is specific and < 1024 chars
+- [ ] Description includes "what" and "when"
+- [ ] YAML frontmatter is valid
+- [ ] Instructions are step-by-step
+- [ ] Examples are concrete and realistic
+- [ ] Dependencies are documented
+- [ ] File paths use forward slashes
+- [ ] Skill activates on relevant queries
+- [ ] Claude follows instructions correctly
+
+## Troubleshooting
+
+**Skill doesn't activate**:
+- Make description more specific with trigger words
+- Include file types and operations in description
+- Add "Use when..." clause with user phrases
+
+**Multiple Skills conflict**:
+- Make descriptions more distinct
+- Use different trigger words
+- Narrow the scope of each Skill
+
+**Skill has errors**:
+- Check YAML syntax (no tabs, proper indentation)
+- Verify file paths (use forward slashes)
+- Ensure scripts have execute permissions
+- List all dependencies
+
+## Examples
+
+See the documentation for complete examples:
+- Simple single-file Skill (commit-helper)
+- Skill with tool permissions (code-reviewer)
+- Multi-file Skill (pdf-processing)
+
+## Output format
+
+When creating a Skill, I will:
+
+1. Ask clarifying questions about scope and requirements
+2. Suggest a Skill name and location
+3. Create the SKILL.md file with proper frontmatter
+4. Include clear instructions and examples
+5. Add supporting files if needed
+6. Provide testing instructions
+7. Validate against all requirements
+
+The result will be a complete, working Skill that follows all best practices and validation rules.

package/framework/.clinerules/skills/spec-analysis/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spec-analysis
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md. Identifying inconsistencies, duplications, ambiguities, and underspecified items.
+---
+
+# Specification & Planning Analysis
+
+## Overview
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation.
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan.
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable**.
+
+## Execution Steps
+
+1.  **Initialize Analysis Context**:
+    *   Load `FEATURE_DIR/spec.md` (or `specs/spec.md`).
+    *   Load `FEATURE_DIR/plan.md` (or `specs/plan.md`).
+    *   Load `FEATURE_DIR/tasks.md` (or `specs/tasks.md`).
+    *   Ensure all files exist; if not, report which are missing (though tasks might not exist yet if only planning).
+
+2.  **Load Artifacts (Progressive Disclosure)**:
+    *   Load only necessary portions relevant to the feature.
+    *   Load `.specify/memory/constitution.md` for validation.
+
+3.  **Build Semantic Models**:
+    *   **Requirements inventory**: Functional + non-functional requirements.
+    *   **User story/action inventory**: User actions + acceptance criteria.
+    *   **Task coverage mapping**: Map task to requirement/story.
+    *   **Constitution rule set**: Principle names and MUST statements.
+
+4.  **Detection Passes**:
+    *   **Duplication**: Near-duplicate requirements.
+    *   **Ambiguity**: Vague adjectives ("fast", "robust") without metrics. Unresolved placeholders (TODO, ???).
+    *   **Underspecification**: Verbs missing objects/outcomes. User stories missing acceptance criteria.
+    *   **Constitution Alignment**: Conflict with MUST principles. Missing mandated sections.
+    *   **Coverage Gaps**: Requirements with zero tasks. Tasks with no mapped requirement.
+    *   **Inconsistency**: Terminology drift. Data entities in plan but absent in spec. Task order contradictions.
+
+5.  **Severity Assignment**:
+    *   **CRITICAL**: Violates constitution, missing core artifact, blocking requirement with zero coverage.
+    *   **HIGH**: Duplicate/conflicting requirement, ambiguous security/performance, untestable AC.
+    *   **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case.
+    *   **LOW**: Style/wording improvements.
+
+6.  **Produce Compact Analysis Report**:
+    *   Output a Markdown report with a findings table: | ID | Category | Severity | Location | Summary | Recommendation |
+    *   **Coverage Summary Table**: Requirement Key | Has Task? | Task IDs | Notes
+    *   **Metrics**: Total Requirements, Total Tasks, Coverage %, Ambiguity Count.
+
+7.  **Provide Next Actions**:
+    *   Recommend resolving CRITICAL issues before implementation.
+    *   Provide explicit suggestions (e.g., "Refine spec", "Adjust plan").
+
+8.  **Offer Remediation**:
+    *   Ask if the user wants concrete remediation edits for top N issues.
+
+## Operating Principles
+
+*   **Context Efficiency**: Focus on actionable findings.
+*   **NEVER modify files** automatically (read-only analysis).
+*   **NEVER hallucinate missing sections**.
+*   **Prioritize constitution violations**.