ac-framework 1.5.0 → 1.7.0

package/framework/.agent/skills/code-review/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: code-review
+description: Review generated code for style, security, and architecture issues; suggest refactorings and performance improvements. Use after implementation is complete, before merging changes, or when refactoring existing code. Follows OWASP guidelines, SOLID principles, and best practices for maintainable code.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "1.0"
+---
+
+# Code Review
+
+Comprehensive code analysis for quality, security, maintainability, and performance optimization.
+
+## When to Use This Skill
+
+Use this skill when:
+- Reviewing code before merging (pre-merge review)
+- After implementation is complete in openspec-apply-change
+- Refactoring existing code for improvement
+- Auditing code for security vulnerabilities
+- Optimizing performance-critical sections
+- Ensuring adherence to project standards
+
+## Instructions
+
+### Step 1: Initial Assessment
+
+1. **Read the code** being reviewed
+2. **Understand the context**:
+   - What problem does this solve?
+   - What are the requirements?
+   - Are there related files/components?
+3. **Identify the scope**:
+   - Lines changed
+   - Files modified
+   - Dependencies introduced
+
+### Step 2: Security Review (OWASP)
+
+Check for common security vulnerabilities:
+
+**Input Validation**:
+- [ ] All user inputs are validated/sanitized
+- [ ] No SQL injection vulnerabilities
+- [ ] No command injection risks
+- [ ] Path traversal prevented
+- [ ] File uploads restricted
+
+**Authentication & Authorization**:
+- [ ] Proper authentication checks
+- [ ] Role-based access control (RBAC)
+- [ ] Session management secure
+- [ ] No hardcoded secrets or credentials
+- [ ] API keys not exposed in client code
+
+**Data Protection**:
+- [ ] Sensitive data encrypted
+- [ ] Proper handling of PII (Personally Identifiable Information)
+- [ ] Secure communication (HTTPS/TLS)
+- [ ] No sensitive data in logs
+
+**Output Encoding**:
+- [ ] XSS prevention (output encoding)
+- [ ] CSRF protection
+- [ ] Content Security Policy headers
+
+### Step 3: Architecture Review
+
+Evaluate against design principles:
+
+**SOLID Principles**:
+- **S**ingle Responsibility: Each class/function has one reason to change
+- **O**pen/Closed: Open for extension, closed for modification
+- **L**iskov Substitution: Subtypes are substitutable for base types
+- **I**nterface Segregation: Small, focused interfaces
+- **D**ependency Inversion: Depend on abstractions, not concretions
+
+**Design Patterns**:
+- Appropriate use of patterns
+- No over-engineering
+- Consistent with project conventions
+
+**Coupling & Cohesion**:
+- Low coupling between modules
+- High cohesion within modules
+- Clear module boundaries
+
+### Step 4: Code Quality Review
+
+**Readability**:
+- [ ] Clear naming (variables, functions, classes)
+- [ ] Consistent formatting
+- [ ] Appropriate comments (why, not what)
+- [ ] No magic numbers/strings
+- [ ] Functions are focused and small
+
+**Maintainability**:
+- [ ] DRY (Don't Repeat Yourself)
+- [ ] No code duplication
+- [ ] Easy to test
+- [ ] Documentation exists
+- [ ] Error handling comprehensive
+
+**Error Handling**:
+- [ ] Exceptions are caught appropriately
+- [ ] Error messages are user-friendly
+- [ ] Failures are logged
+- [ ] Graceful degradation
+
+### Step 5: Performance Review
+
+**Efficiency**:
+- [ ] No unnecessary computations
+- [ ] Efficient data structures
+- [ ] Database queries optimized
+- [ ] No N+1 query problems
+- [ ] Caching used appropriately
+
+**Resource Usage**:
+- [ ] Memory leaks prevented
+- [ ] Large objects disposed properly
+- [ ] No blocking operations on main thread
+- [ ] Async/await used correctly
+
+### Step 6: Testing Review
+
+- [ ] Unit tests exist for new logic
+- [ ] Tests cover edge cases
+- [ ] Integration tests for API contracts
+- [ ] Test names are descriptive
+- [ ] Mocks are appropriate
+- [ ] Test coverage is adequate (>80%)
+
+### Step 7: Documentation Review
+
+- [ ] Code comments explain complex logic
+- [ ] Public APIs are documented (JSDoc, docstrings)
+- [ ] README updated if needed
+- [ ] Architecture Decision Records (ADRs) for significant changes
+- [ ] Changelog entries added
+
+### Step 8: Compile Findings
+
+Organize issues by severity:
+
+```
+## Code Review Report
+
+### Critical (Block Merge)
+1. [Security vulnerability description]
+   - File: path/to/file.ext:line
+   - Issue: [detailed explanation]
+   - Fix: [recommended solution]
+
+### High (Should Fix)
+1. [Performance or architecture issue]
+   ...
+
+### Medium (Nice to Have)
+1. [Style or readability improvement]
+   ...
+
+### Low (Suggestions)
+1. [Minor improvements]
+   ...
+
+### Positive Feedback
+- [What was done well]
+```
+
+### Step 9: Provide Actionable Feedback
+
+For each issue:
+1. **Explain the problem** (why it's an issue)
+2. **Show the problematic code**
+3. **Suggest a fix** (with code example if possible)
+4. **Reference best practices** (OWASP, SOLID, etc.)
+
+### Step 10: Follow-up
+
+1. **Track fixes** - Ensure all critical/high issues are addressed
+2. **Re-review** if significant changes are made
+3. **Update documentation** based on review findings
+4. **Share learnings** - Common issues can inform team guidelines
+
+## Integration with OpenSpec
+
+- Run after `openspec-apply-change` completes
+- Block merge in `openspec-verify-change` until critical issues resolved
+- Link review findings to tasks in tasks.md
+- Document architectural decisions in design.md
+
+## Guardrails
+
+- **Be constructive** - Focus on the code, not the person
+- **Explain why** - Don't just say "change this", explain the reason
+- **Balance thoroughness with pragmatism** - Not everything needs to be perfect
+- **Respect existing patterns** - Don't force changes unless there's a good reason
+- **Consider the context** - Startup MVP vs. enterprise system have different standards
+
+## Review Checklist Template
+
+```markdown
+## Security
+- [ ] Input validation
+- [ ] Authentication/authorization
+- [ ] No secrets in code
+- [ ] XSS/CSRF protection
+
+## Architecture
+- [ ] SOLID principles
+- [ ] Appropriate patterns
+- [ ] Low coupling
+
+## Quality
+- [ ] Naming clarity
+- [ ] No duplication
+- [ ] Error handling
+- [ ] Comments where needed
+
+## Performance
+- [ ] Efficient algorithms
+- [ ] No N+1 queries
+- [ ] Proper async usage
+
+## Testing
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Edge cases covered
+
+## Documentation
+- [ ] Code comments
+- [ ] API docs
+- [ ] README updated
+```
+
+## Requirements
+
+- Access to the codebase
+- Understanding of project conventions
+- Knowledge of security best practices (OWASP)
+- Familiarity with design patterns
+- Understanding of performance optimization
+
+## See Also
+
+- `secure-coding-cybersecurity` - Deep security audit
+- `performance-optimizer` - Performance analysis
+- `code-maintainability` - Maintainability assessment
+- `openspec-verify-change` - Verification with review gates

package/framework/.agent/skills/context-synthesizer/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: context-synthesizer
+description: Manage memory in long projects and summarize the current state to prevent agent context loss. Use when starting a new session on a long-running project, resuming work after a break, switching contexts between tasks, or when context window is approaching limits. Ensures continuity and consistency across sessions.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "1.0"
+---
+
+# Context Synthesizer
+
+Memory management and context summarization for long-running projects to maintain continuity and prevent information loss.
+
+## When to Use This Skill
+
+Use this skill when:
+- Starting a new session on an existing project
+- Resuming work after a break or context switch
+- Approaching context window limits during long tasks
+- Switching between different parts of a large codebase
+- Onboarding to a project mid-development
+- Before executing complex multi-step operations
+
+## Instructions
+
+### Step 1: Load Project Context
+
+1. **Read project-index.md** (if exists):
+   - Project structure
+   - Key directories and their purposes
+   - Domain boundaries
+   - Active changes
+
+2. **Check OpenSpec status**:
+   ```bash
+   acfm spec status --json
+   ```
+   - Which spec directory is used (.acfm/ or openspec/)
+   - Active changes
+   - Recently archived changes
+
+3. **List active changes**:
+   ```bash
+   acfm spec list --json
+   ```
+
+### Step 2: Summarize Current State
+
+Create a state summary:
+
+```markdown
+## Project Context Summary
+
+**Project**: [Name]
+**Last Updated**: [Date]
+**Session**: [Session identifier]
+
+### Current State
+
+**Active Changes**:
+1. [Change 1] - [Brief description] - [Status]
+2. [Change 2] - [Brief description] - [Status]
+
+**Recently Completed**:
+1. [Change 3] - [Completion date]
+
+**Architecture Overview**:
+- [Key architectural decisions]
+- [Technology stack]
+- [Important patterns in use]
+
+### Current Focus
+
+**Primary Task**: [What we're working on now]
+**Next Steps**: [Immediate next actions]
+**Blockers**: [Any blocking issues]
+
+### Key Files Modified Recently
+
+1. [file1.ext] - [Why it was changed]
+2. [file2.ext] - [Why it was changed]
+
+### Important Context
+
+- [Critical information needed for current work]
+- [Decisions made in previous sessions]
+- [Patterns to follow]
+```
+
+### Step 3: Identify Relevant Artifacts
+
+For the current task, identify:
+
+**Specifications**:
+- Which spec applies to current work?
+- Where are the delta specs located?
+- What are the acceptance criteria?
+
+**Design Documents**:
+- Architecture diagrams
+- Data models
+- API contracts
+
+**Task Lists**:
+- Which tasks are in progress?
+- Which are completed?
+- Dependencies between tasks
+
+**Previous Work**:
+- Similar implementations to reference
+- Relevant tests
+- Documentation
+
+### Step 4: Synthesize Concise Context
+
+Create a focused summary for the current task:
+
+```markdown
+## Working Context: [Task Name]
+
+**Goal**: [One-sentence objective]
+
+**Background**:
+[2-3 sentences of relevant history]
+
+**Requirements** (from spec):
+- [Requirement 1]
+- [Requirement 2]
+
+**Current State**:
+- [What's already done]
+- [What's in progress]
+- [What's pending]
+
+**Technical Context**:
+- **Language/Framework**: [Tech stack]
+- **Key Files**: [List of relevant files]
+- **Patterns**: [Architectural patterns to follow]
+- **Constraints**: [Limitations or requirements]
+
+**References**:
+- Spec: [Link to spec]
+- Design: [Link to design doc]
+- Similar Implementation: [Link to reference code]
+```
+
+### Step 5: Update Context Database
+
+If using vector database (Pinecone, Weaviate, etc.):
+
+1. **Index new artifacts**:
+   - Summarize and embed new specifications
+   - Index design documents
+   - Store task completion summaries
+
+2. **Update project index**:
+   ```markdown
+   ## Recent Updates
+   
+   ### [Date]
+   - [Change summary]
+   - [Files affected]
+   - [Decisions made]
+   ```
+
+3. **Tag and categorize**:
+   - Domain tags (auth, payments, ui, etc.)
+   - Status tags (active, completed, archived)
+   - Priority tags (critical, high, medium, low)
+
+### Step 6: Provide Context Before Tasks
+
+Before starting work, provide the agent with:
+
+```
+## Context for Current Session
+
+**Project**: [Name]
+**Working On**: [Specific task/change]
+**Session Goal**: [What to accomplish]
+
+### Relevant Specifications
+
+[Summary of applicable specs]
+
+### Current State
+
+[What's already done]
+[What needs to be done]
+
+### Key Information
+
+- [Important fact 1]
+- [Important fact 2]
+- [Decision to remember]
+
+### Files to Focus On
+
+1. [Primary file]
+2. [Secondary file]
+3. [Test file]
+
+### Patterns to Follow
+
+[Reference to existing patterns]
+```
+
+### Step 7: Archive Old Context
+
+Periodically clean up:
+
+1. **Archive completed changes**:
+   ```bash
+   acfm spec archive [change-name]
+   ```
+
+2. **Summarize archived work**:
+   ```markdown
+   ## Archive Summary: [Change Name]
+   
+   **Completed**: [Date]
+   **Summary**: [What was done]
+   **Key Files**: [Files modified]
+   **Decisions**: [Important decisions made]
+   ```
+
+3. **Compress old context**:
+   - Summarize long conversations
+   - Extract key decisions
+   - Remove obsolete information
+
+## Integration with OpenSpec
+
+- Load context from `.acfm/` or `openspec/` directories
+- Reference active changes in context summaries
+- Link to specifications and design documents
+- Track task completion status
+
+## Output Format
+
+When providing context:
+
+```
+## Current Context Loaded
+
+**Project**: [Name]
+**Session ID**: [ID]
+**Context Size**: [Token count/Compressed size]
+
+### Active Changes (3)
+1. user-authentication - JWT implementation - In Progress
+2. api-rate-limiting - Middleware setup - Pending
+3. database-migration - Schema updates - Completed
+
+### Current Focus
+**Change**: user-authentication
+**Task**: Implement token refresh
+**Status**: 60% complete
+
+### Key Files
+- src/services/auth.js
+- src/middleware/auth.js
+- tests/auth.test.js
+
+### Recent Decisions
+1. Use Redis for token storage
+2. Refresh tokens valid for 7 days
+3. Access tokens valid for 15 minutes
+
+### Next Steps
+1. Implement refresh token endpoint
+2. Add token rotation logic
+3. Write integration tests
+
+### Context Source
+- project-index.md (last modified: 2024-01-15)
+- .acfm/changes/user-authentication/ (active)
+- references/auth-patterns.md
+```
+
+## Guardrails
+
+- **Keep summaries concise** - Focus on relevant information
+- **Update regularly** - Context gets stale quickly
+- **Version context** - Track when context was last updated
+- **Prioritize active work** - Don't load context for completed tasks
+- **Compress intelligently** - Summarize without losing critical details
+- **Cross-reference sources** - Always link to original documents
+
+## Context Compression Strategies
+
+**High Priority** (Always include):
+- Current task requirements
+- Active change specifications
+- Recent decisions
+- Blocking issues
+
+**Medium Priority** (Summarize):
+- Completed changes (last 3)
+- Architecture overview
+- Key patterns
+- Active dependencies
+
+**Low Priority** (Reference only):
+- Completed changes (older)
+- Archived work
+- General documentation
+- Historical context
+
+## Requirements
+
+- Access to project-index.md
+- Access to OpenSpec directories
+- Storage for context summaries (file or vector DB)
+- Understanding of what's relevant vs. noise
+
+## See Also
+
+- `acfm-spec-workflow` - Understand OpenSpec structure
+- `project-index` - Generate/maintain project documentation
+- `sync-index` - Keep index in sync with codebase
+- `openspec-verify-change` - Verify context is current