ac-framework 1.5.0 → 1.6.0

package/framework/.clinerules/skills/openspec-verify-change/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: openspec-verify-change
+description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
+license: MIT
+compatibility: Requires acfm CLI (bundled).
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   acfm spec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   acfm spec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

package/framework/.clinerules/skills/performance-optimizer/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: performance-optimizer
+description: Transform the agent into a performance engineer. Apply methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage).
+---
+
+# Performance Optimization
+
+## Overview
+
+Use this skill to analyze and improve the performance of the codebase. Focus on measurable improvements, not premature optimization.
+
+## Workflow
+
+1.  **Measure First**:
+    *   Never optimize without a baseline.
+    *   Use profiling tools or simple timing logs to identify bottlenecks.
+    *   "What gets measured, gets managed."
+
+2.  **Analyze and Hypothesize**:
+    *   Identify the root cause: CPU, Memory, I/O, or Network?
+    *   Look for common culprits: N+1 queries, unoptimized loops, large payload sizes, unnecessary re-renders (frontend).
+
+3.  **Optimize**:
+    *   **Algorithmic**: Improve Big-O complexity (e.g., O(n^2) -> O(n)).
+    *   **Caching**: Implement caching strategies (in-memory, Redis, HTTP caching).
+    *   **Database**: Add indexes, optimize queries, use batching.
+    *   **Frontend**: Lazy loading, memoization, code splitting, asset optimization.
+
+4.  **Verify**:
+    *   Run the measurements again.
+    *   Confirm the improvement.
+    *   Ensure no regression in functionality.
+
+## Techniques & Patterns
+
+*   **Database**: Explain Analyze, Indexing, Connection Pooling.
+*   **Backend**: Async processing, Caching layers, Load balancing.
+*   **Frontend**: Virtualization for long lists, Debouncing/Throttling events.
+
+## Output
+
+*   Create a brief report of findings and improvements.
+*   Update code with optimized solution.

package/framework/.clinerules/skills/project-constitution/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: project-constitution
+description: Manage the project's core principles and ensuring alignment. Create or update the project constitution from interactive or provided principle inputs.
+---
+
+# Project Constitution Management
+
+## Overview
+
+You are updating the project constitution at `.specify/memory/constitution.md` (or `.specify/.specify/memory/constitution.md` if the user's structure differs). This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If the constitution file does not exist yet, it should have been initialized from a template during project setup. If it's missing, copy the template first (check `.specify/templates/constitution-template.md`).
+
+## Execution Flow
+
+1.  **Load the existing constitution**.
+    *   Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+    *   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2.  **Collect/derive values for placeholders**:
+    *   If user input (conversation) supplies a value, use it.
+    *   Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+    *   For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+    *   `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+        *   MAJOR: Backward incompatible governance/principle removals or redefinitions.
+        *   MINOR: New principle/section added or materially expanded guidance.
+        *   PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+    *   If version bump type ambiguous, propose reasoning before finalizing.
+
+3.  **Draft the updated constitution content**:
+    *   Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+    *   Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+    *   Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+    *   Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4.  **Consistency propagation checklist**:
+    *   Check if `.specify/templates/plan-template.md`, `.specify/templates/spec-template.md`, and any other templates align with the updated constitution.
+    *   Update runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`) if they reference changed principles.
+
+5.  **Produce a Sync Impact Report** (prepend as an HTML comment at top of the constitution file after update):
+    *   Version change: old → new
+    *   List of modified principles (old title → new title if renamed)
+    *   Added/Removed sections
+    *   Templates requiring updates (✅ updated / ⚠ pending) with file paths
+    *   Follow-up TODOs.
+
+6.  **Validation before final output**:
+    *   No remaining unexplained bracket tokens.
+    *   Version line matches report.
+    *   Dates ISO format YYYY-MM-DD.
+    *   Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7.  **Write the completed constitution** back to the file (overwrite).
+
+8.  **Output a final summary**:
+    *   New version and bump rationale.
+    *   Any files flagged for manual follow-up.
+    *   Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+## Formatting & Style Requirements
+
+*   Use Markdown headings exactly as in the template.
+*   Wrap long rationale lines to keep readability (<100 chars ideally).
+*   Keep a single blank line between sections.
+*   Avoid trailing whitespace.
+*   If critical info missing, insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report.

package/framework/.clinerules/skills/project-index/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: project-index
+description: "Analyze codebase structure, generate domain-specific sub-skills (UI, Backend, Database, etc.), and create agent-guidance files to help AI agents navigate and develop consistently within a project. Use when onboarding to a new codebase, creating project documentation, or setting up agent guidance systems."
+---
+
+# Project Index
+
+A skill for analyzing existing codebases and creating structured guidance systems for AI agents. Generates domain-specific knowledge and navigation aids without modifying source code locations.
+
+## When to Use
+
+Use this skill when:
+- Starting work on an unfamiliar codebase
+- Creating agent guidance for team projects
+- Setting up structured project documentation
+- Analyzing project architecture and patterns
+- Creating domain-specific agent knowledge (UI, Backend, Database, etc.)
+
+## Quick Start
+
+
+1. Scan the codebase structure
+
+ ```bash
+python ./skills/project-index/scripts/scan_codebase.py /path/to/project --output codebase_index.json
+```
+2. Analyze the generated index and identify domains
+3. Create sub-skills using skill-writer
+4. Generate agent-guidance files
+
+
+## Instructions
+
+### Step 1: Scan the Codebase
+
+Run the scanning script to generate a complete structural map:
+
+```bash
+python ./skills/project-index/scripts/scan_codebase.py <project_path> --output codebase_index.json
+```
+
+**Important**: The script provides a structural overview. You MUST also:
+- Read key configuration files (package.json, tsconfig.json, etc.)
+- Examine existing code patterns and conventions
+- Understand the project's architecture and dependencies
+- Review README files and existing documentation
+
+**Parameters**:
+- `<project_path>`: Absolute path to the project root
+- `--output`: Output filename (default: `codebase_index.json`)
+
+**Excluded directories**: `.git`, `node_modules`, `__pycache__`, `dist`, `build`, `.next`, `.expo`
+
+### Step 2: Analyze the Index
+
+Review the generated `codebase_index.json` and:
+
+1. **Identify main domains**: UI, Backend, Database, API, Components, Utils, etc.
+2. **Map relationships**: How do domains interact?
+3. **Find patterns**: Naming conventions, folder structures, architectural patterns
+4. **Locate key files**: Entry points, configuration files, core modules
+
+**CRITICAL**: Do not rely solely on the JSON index. Actually explore the codebase:
+- Open and read representative files from each domain
+- Understand the tech stack and frameworks used
+- Identify coding standards and conventions
+- Note any custom patterns or abstractions
+
+### Step 3: Create Sub-Skills
+
+For each identified domain, create a focused sub-skill using **skill-writer**:
+
+```bash
+# Load the skill-writer skill first, then:
+# Create sub-skills like project-index-ui, project-index-backend, etc.
+```
+
+Each sub-skill should:
+- Focus on ONE domain only
+- Include specific navigation guidance
+- Reference relevant agent-guidance files
+- Be discoverable with clear triggers
+
+**Use the template**: `./skills/project-index/templates/skill-template.md`
+
+**Naming convention**: `project-index-<domain>` (e.g., `project-index-ui`, `project-index-backend`)
+
+### Step 4: Generate Agent-Guidance Files
+
+Create `agent-<name>.md` files in relevant project directories:
+
+**Use the template**: `./skills/project-index/templates/agent-template.md`
+
+Each file should contain:
+- **Purpose**: Clear description of the directory/section
+- **Methodology & Patterns**: Design patterns and architectural approaches used
+- **Best Practices**: Explicit do's and don'ts
+- **Key Components/Files**: Important files in this section
+- **Integration**: How to add new elements following existing patterns
+
+## Templates
+
+### Sub-Skill Template
+
+Location: `./skills/project-index/templates/skill-template.md`
+
+```markdown
+---
+name: project-index-{{domain}}
+description: "Domain-specific knowledge for {{domain}} in this project. Use when working on {{path}} or when user mentions {{domain}}-related tasks."
+---
+
+# {{Domain}} Domain Guide
+
+## Overview
+Context and purpose of the {{domain}} layer located in `{{path}}`.
+
+## Navigation
+- **Main Logic**: [Where core logic resides]
+- **Data Flow**: [How data moves through this domain]
+- **Key Files**: [Important entry points]
+
+## Guidelines
+1. [Specific guideline 1]
+2. [Specific guideline 2]
+
+## Reference
+See `agent-{{domain}}.md` in the directory for implementation details.
+```
+
+### Agent-Guidance Template
+
+Location: `./skills/project-index/templates/agent-template.md`
+
+```markdown
+# Agent Guide: {{name}}
+
+## Purpose
+Guidance for working in `{{path}}` following established patterns and practices.
+
+## Methodology & Patterns
+- **Pattern 1**: [Description]
+- **Pattern 2**: [Description]
+
+## Best Practices
+- **Do**: [Recommended practice]
+- **Avoid**: [Practice to avoid]
+
+## Key Files
+- [Important file 1]
+- [Important file 2]
+
+## Integration
+Follow the structure of `{{example_file}}` when adding new elements.
+```
+
+## Best Practices
+
+### DO
+- **Investigate thoroughly**: Read actual code files, not just the index
+- **Be specific**: Provide concrete examples and file paths
+- **Keep it focused**: One sub-skill per domain
+- **Use skill-writer**: Follow proper skill creation workflow
+- **Update incrementally**: Refine guidance as you learn more
+- **Test navigation**: Verify agents can find relevant information
+
+### AVOID
+- **Relying only on scripts**: The index is a starting point, not the whole picture
+- **Creating mega-skills**: Keep each sub-skill focused on one domain
+- **Vague descriptions**: Be specific about patterns and conventions
+- **Duplicating docs**: Reference existing READMEs rather than copying
+- **Hardcoded assumptions**: Note when patterns vary across the codebase
+
+## File Structure
+
+```
+.skills/project-index/
+├── SKILL.md                    # This file
+├── templates/
+│   ├── skill-template.md       # Template for sub-skills
+│   └── agent-template.md       # Template for agent guides
+└── scripts/
+    └── scan_codebase.py        # Codebase scanning utility
+```
+
+## Advanced Usage
+
+### Progressive Enhancement
+
+Start with basic structure analysis, then iteratively improve:
+
+1. **Phase 1**: Scan and identify main domains
+2. **Phase 2**: Create basic sub-skills with navigation
+3. **Phase 3**: Add detailed agent-guidance files
+4. **Phase 4**: Refine based on actual usage
+
+### Multi-Project Setup
+
+For organizations with multiple projects:
+- Create base patterns in a shared skill
+- Extend with project-specific sub-skills
+- Maintain consistent naming conventions
+
+### Validation Checklist
+
+Before considering the index complete:
+- [ ] Scanned codebase with script
+- [ ] Manually reviewed key files and directories
+- [ ] Identified all major domains
+- [ ] Created focused sub-skills using skill-writer
+- [ ] Generated agent-guidance files in relevant directories
+- [ ] Verified navigation paths are clear
+- [ ] Tested with sample queries
+
+## Troubleshooting
+
+### Script fails to run
+- Check Python 3 is installed
+- Verify the project path is absolute and exists
+- Ensure write permissions for output directory
+
+### Sub-skills not activating
+- Use skill-writer to validate the skill structure
+- Check description includes trigger words
+- Verify file location matches skill name
+
+### Guidance feels incomplete
+- Remember: The index is a living document
+- Add more detail as you work with the codebase
+- Update agent-guidance files based on new discoveries
+
+## Credits
+
+Original concept and implementation by b4san.

package/framework/.clinerules/skills/project-index/scripts/scan_codebase.py

@@ -0,0 +1,47 @@
+import os
+import json
+import argparse
+
+def scan_project(root_dir):
+    project_structure = {
+        "root": root_dir,
+        "directories": {},
+        "files": []
+    }
+    
+    # Common directories to ignore
+    ignore_dirs = {'.git', 'node_modules', '__pycache__', 'dist', 'build', '.next', '.expo'}
+    
+    for root, dirs, files in os.walk(root_dir):
+        # Filter ignored directories
+        dirs[:] = [d for d in dirs if d not in ignore_dirs]
+        
+        rel_path = os.path.relpath(root, root_dir)
+        if rel_path == '.':
+            rel_path = ''
+            
+        for d in dirs:
+            dir_path = os.path.join(rel_path, d)
+            project_structure["directories"][dir_path] = []
+            
+        for f in files:
+            file_path = os.path.join(rel_path, f)
+            project_structure["files"].append(file_path)
+            if rel_path in project_structure["directories"]:
+                project_structure["directories"][rel_path].append(f)
+            elif rel_path == '':
+                # Root files
+                pass
+
+    return project_structure
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Scan codebase for project-index skill")
+    parser.add_argument("path", help="Path to the codebase root")
+    parser.add_argument("--output", help="Path to save the JSON result", default="codebase_index.json")
+    args = parser.parse_args()
+    
+    structure = scan_project(args.path)
+    with open(args.output, 'w') as f:
+        json.dump(structure, f, indent=2)
+    print(f"Codebase scanned. Index saved to {args.output}")

package/framework/.clinerules/skills/project-index/templates/agent-template.md

@@ -0,0 +1,18 @@
+# Agent Guide: {{category}}
+
+## Purpose
+This document guides the agent through the patterns, best practices, and methodologies used in the `{{path}}` directory of this codebase.
+
+## Methodology & Patterns
+- **Pattern 1**: {{description_1}}
+- **Pattern 2**: {{description_2}}
+
+## Best Practices
+- **Do**: {{do_practice}}
+- **Avoid**: {{avoid_practice}}
+
+## Key Components / Files
+{{file_list}}
+
+## Integration
+To integrate new elements here, follow the structure of `{{example_file}}`.

package/framework/.clinerules/skills/project-index/templates/skill-template.md

@@ -0,0 +1,20 @@
+---
+name: project-index-{{category}}
+description: Domain-specific knowledge for {{category}} in this project. Use when working on {{path}}.
+---
+
+# {{category}} Skill
+
+## Overview
+This sub-skill provides deep context for the {{category}} layer of the project located at `{{path}}`.
+
+## Navigation
+- **Primary Logic**: {{logic_description}}
+- **Data Flow**: {{data_flow}}
+
+## Guidelines
+1. {{guideline_1}}
+2. {{guideline_2}}
+
+## Reference Files
+Refer to `agent-{{category}}.md` in the directory for implementation details.