ac-framework 1.9.2 → 1.9.3

package/framework/new_project/.trae/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