ac-framework 1.7.0 → 1.9.0

package/README.md

@@ -118,6 +118,32 @@ acfm spec new my-feature
 | `acfm spec validate <name>` | Validate change structure | `--json` |
 | `acfm spec schemas` | List available workflow schemas | `--json` |
 
+### Memory System Commands (Persistent Learning)
+
+AC Framework includes an **autonomous memory system** that learns from your development work.
+
+| Command | Description | Flags |
+|---------|-------------|-------|
+| `acfm memory init` | Initialize memory database | `--json` |
+| `acfm memory recall [task]` | Recall relevant context | `--project`, `--change`, `--json` |
+| `acfm memory search <query>` | Search saved memories | `--type`, `--limit`, `--json` |
+| `acfm memory save <content>` | Save memory manually | `--type`, `--tags`, `--importance` |
+| `acfm memory get <id>` | View memory details | `--json` |
+| `acfm memory timeline <id>` | Timeline around memory | `--window`, `--json` |
+| `acfm memory patterns` | Analyze patterns | `--type`, `--json` |
+| `acfm memory stats` | Memory statistics | `--project`, `--json` |
+| `acfm memory export [file]` | Export memories | `--shareable-only` |
+| `acfm memory import <file>` | Import memories | `--merge` |
+
+**What gets saved automatically:**
+- Architectural decisions from proposals/designs
+- Bugfix patterns and solutions  
+- Performance optimizations
+- Refactoring techniques
+- Security fixes
+
+**Privacy:** Content between `<private>...</private>` tags is automatically redacted.
+
 **Tip:** Add `--json` to any command for programmatic output.
 
 ---

package/bin/postinstall.js

@@ -22,7 +22,18 @@ console.log('      acfm spec validate       Validate change structure');
 console.log('      acfm spec archive        Archive a completed change');
 console.log('      acfm spec schemas        List workflow schemas');
 console.log();
-console.log('    Tip: Add --json to any spec command for machine-readable output.');
+console.log('    Memory System (Persistent Learning)');
+console.log('      acfm memory init         Initialize memory database');
+console.log('      acfm memory recall       Recall relevant context');
+console.log('      acfm memory search       Search memories');
+console.log('      acfm memory save         Save memory manually');
+console.log('      acfm memory stats        View memory statistics');
+console.log();
+console.log('    MCP (Model Context Protocol) Servers');
+console.log('      acfm memory install-mcps   Install MCP servers for AI assistants');
+console.log('      acfm memory uninstall-mcps Uninstall MCP servers from AI assistants');
+console.log();
+console.log('    Tip: Add --json to any command for machine-readable output.');
 console.log();
 
 if (isWin) {
@@ -37,3 +48,12 @@ if (isWin) {
   console.log('    4. Restart your terminal');
   console.log();
 }
+
+// Auto-detect and install MCPs for supported assistants
+try {
+  const { detectAndInstallMCPs } = require('../src/services/mcp-installer');
+  detectAndInstallMCPs();
+} catch (error) {
+  // Silently fail if MCP installer is not available yet
+  // This allows the framework to work without MCP dependencies during early development
+}

package/framework/.agent/skills/acfm-memory/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: acfm-memory
+description: Autonomous memory system for persistent learning across sessions. Automatically saves architectural decisions, bugfixes, patterns, and insights. Use to recall context from previous work and build institutional knowledge.
+---
+
+# AC Framework Memory System
+
+## Overview
+
+The AC Framework Memory System provides **autonomous persistent memory** for AI agents. It automatically detects and saves valuable knowledge during development, then recalls relevant context when needed.
+
+**Key Capabilities:**
+- **Automatic saving**: Detects and stores important decisions, patterns, and solutions
+- **Full-text search**: Find relevant memories instantly
+- **Context recall**: Get relevant knowledge before starting tasks
+- **Pattern analysis**: Detect recurring themes and errors
+- **Timeline view**: See chronological context around any memory
+
+## When to Use This Skill
+
+### Before Starting Work
+- **Recall relevant context**: `acfm memory recall "<task description>"`
+- **Check for similar changes**: `acfm memory search "<topic>"`
+- **Review patterns**: `acfm memory patterns`
+
+### During Work (Automatic)
+The agent automatically saves memories when:
+- Completing architectural proposals
+- Fixing bugs (especially after multiple attempts)
+- Refactoring code successfully
+- Optimizing performance
+- Discovering important patterns
+
+### After Work
+- **Review learnings**: `acfm memory stats`
+- **Export for sharing**: `acfm memory export team-memory.json`
+- **Find gaps**: `acfm memory patterns --min-frequency 1`
+
+## Memory Types
+
+| Type | Description | Auto-Trigger |
+|------|-------------|--------------|
+| `architectural_decision` | Major design decisions | After proposal/design |
+| `bugfix_pattern` | Solutions to bugs | After fixing error |
+| `refactor_technique` | Successful refactoring patterns | After refactor |
+| `performance_insight` | Optimization learnings | After performance work |
+| `security_fix` | Security vulnerability fixes | After security patch |
+| `api_pattern` | API design patterns | After API work |
+| `convention` | Project conventions | After establishing pattern |
+| `workaround` | Temporary solutions | After implementing hack |
+| `context_boundary` | System limitations | After defining boundaries |
+
+## Commands
+
+### Core Commands
+
+#### Initialize Memory System
+```bash
+acfm memory init
+```
+Creates the SQLite database at `~/.acfm/memory.db`.
+
+#### Save Memory (Manual)
+```bash
+acfm memory save "Descripción de la decisión o patrón" \
+  --type architectural_decision \
+  --importance high \
+  --tags "react,performance"
+```
+
+#### Recall Context
+```bash
+# For specific task
+acfm memory recall "implementing authentication"
+
+# For current project (general context)
+acfm memory recall
+```
+
+#### Search Memories
+```bash
+# Basic search
+acfm memory search "JWT"
+
+# Filtered search
+acfm memory search "database" --type architectural_decision --importance high
+```
+
+### Advanced Commands
+
+#### Timeline View
+```bash
+acfm memory timeline <memory-id>
+```
+Shows what happened before and after a specific memory.
+
+#### Connections
+```bash
+acfm memory connections <memory-id> --depth 2
+```
+Shows related memories as a graph.
+
+#### Pattern Detection
+```bash
+acfm memory patterns
+acfm memory patterns --type bugfix_pattern
+```
+Finds recurring topics and frequent error types.
+
+#### Predictive Recall
+```bash
+acfm memory anticipate "caching strategy"
+```
+Predicts which memories will be relevant for a future task.
+
+#### Statistics
+```bash
+acfm memory stats
+acfm memory stats --project /path/to/project
+```
+
+#### Export/Import
+```bash
+# Export for sharing
+acfm memory export team-memory.json
+
+# Import shared knowledge
+acfm memory import team-memory.json
+```
+
+## Auto-Save Behavior
+
+### What Triggers Auto-Save
+
+The agent evaluates content using a confidence score (0-1):
+
+**High confidence triggers (auto-save):**
+- Contains decision keywords: "decidimos", "optamos", "mejor usar"
+- Describes solution to problem
+- Contains architectural guidance
+- Has error + solution pair
+- Takes >10 minutes to resolve
+
+**Low confidence (skip):**
+- Very short content (<50 chars)
+- Contains specific IDs/UUIDs
+- Temporary TODOs
+- Obvious/common knowledge
+
+### Confidence Scoring
+
+```
+Base: 0.5
++ Decision keywords: +0.25
++ Contains solution: +0.20
++ Bug fix: +0.15
++ Architecture: +0.20
++ Optimization: +0.15
++ Security: +0.25
+- Too short: -0.20
+- Specific IDs: -0.15
+- TODO/FIXME: -0.20
+
+Threshold for auto-save: 0.60
+```
+
+### Notification
+
+When auto-saving, the agent will display:
+```
+💾 Memory saved: [Brief description of what was learned]
+   Type: bugfix_pattern | Confidence: 85%
+```
+
+## Privacy
+
+Content between `<private>` tags is automatically redacted:
+
+```markdown
+Decidimos usar AWS para hosting. <private>Usaremos la cuenta
+producción-env-123</private> para el deployment.
+```
+
+Saved as:
+```
+Decidimos usar AWS para hosting. [REDACTED PRIVATE CONTENT]
+```
+
+## Integration with Spec Workflow
+
+### Before Creating Artifacts
+
+When you request `acfm spec instructions`, the system automatically:
+
+1. Queries memories related to the change topic
+2. Includes relevant memories in the response
+3. Displays them as context for the agent
+
+Example output:
+```json
+{
+  "instruction": "...",
+  "relevantMemories": [
+    {
+      "id": 42,
+      "type": "architectural_decision",
+      "content": "Previous auth system used JWT...",
+      "importance": "high"
+    }
+  ]
+}
+```
+
+### During Apply Phase
+
+When implementing tasks, the system recalls:
+- Patterns from similar previous tasks
+- Bugfixes related to current work
+- Performance insights for optimization tasks
+
+## Best Practices
+
+### For Agents
+
+1. **Always recall before starting**: Check `acfm memory recall` for relevant context
+2. **Let auto-save work**: Don't manually save everything - trust the confidence scoring
+3. **Use topic keys**: When manually saving, use consistent topic keys for deduplication
+4. **Mark importance**: Critical decisions should be marked `critical` or `high`
+5. **Add tags**: Tags improve searchability
+
+### For Users
+
+1. **Initialize once**: Run `acfm memory init` per machine
+2. **Review periodically**: Check `acfm memory stats` to see what's been learned
+3. **Export regularly**: Share knowledge with team via `acfm memory export`
+4. **Prune old data**: Use `acfm memory prune` to archive obsolete memories
+5. **Use private tags**: Mark sensitive content with `<private>` tags
+
+## Examples
+
+### Example 1: Bug Fix
+
+**Agent fixes an authentication bug:**
+```
+💾 Memory saved: JWT refresh token fails when expired during request
+   Type: bugfix_pattern | Confidence: 87%
+   Solution: Implement token refresh interceptor
+```
+
+**Later, similar task:**
+```bash
+$ acfm memory recall "authentication token"
+→ [Memory #42] JWT refresh token fails when expired...
+```
+
+### Example 2: Architectural Decision
+
+**Agent completes proposal:**
+```
+💾 Memory saved: Microservices architecture chosen for scalability
+   Type: architectural_decision | Confidence: 92%
+   Tags: ["architecture", "microservices", "scalability"]
+```
+
+**Weeks later, new service:**
+```bash
+$ acfm memory search "microservices" --type architectural_decision
+→ [Memory #15] Microservices architecture chosen for scalability
+```
+
+### Example 3: Pattern Detection
+
+```bash
+$ acfm memory patterns --type bugfix_pattern
+
+Detected patterns:
+- null-check-react (3×) - Null checks in React components
+- async-race-condition (2×) - Race conditions in async code
+- cors-preflight (2×) - CORS preflight issues
+
+Recommendation: Consider adding ESLint rules for null checks
+```
+
+## Troubleshooting
+
+### Memory not saving
+- Check initialization: `acfm memory init`
+- Content may be below confidence threshold
+- May contain too many specific IDs
+
+### Search not finding results
+- Try broader keywords
+- Use `acfm memory recall` without query for general context
+- Check if memories exist: `acfm memory stats`
+
+### Database locked
+- Close other instances of `acfm`
+- SQLite is single-writer; wait a moment and retry
+
+## Related Skills
+
+- `acfm-spec-workflow` - Foundation for spec-driven development
+- `context-synthesizer` - For managing context in long conversations
+- `systematic-debugging` - For complex problem resolution
+
+## CLI Reference
+
+See `acfm memory --help` for all commands and options.
+
+---
+
+**Remember**: The memory system learns from every interaction. The more you use it, the more valuable it becomes.

package/framework/.agent/workflows/ac-lite.md

@@ -0,0 +1,192 @@
+**Fundamental Principle**: *"Quality with focused context. Load only what is necessary, when it is necessary."*
+
+---
+
+## Purpose
+
+`ac-lite` keeps the same spec-driven quality bar as `ac.md`, but reduces token usage by:
+
+1. Loading only the core workflow skills by default.
+2. Activating extra skills only when objective risk gates require them.
+3. Enforcing mandatory quality checkpoints before implementation and archive.
+
+---
+
+## Default Skill Set (Always Load)
+
+These are the only mandatory skills for every change:
+
+1. `acfm-spec-workflow`
+2. `openspec-new-change` OR `openspec-ff-change`
+3. `openspec-continue-change`
+4. `openspec-apply-change`
+5. `openspec-verify-change`
+6. `openspec-archive-change`
+
+---
+
+## Conditional Skills (Load Only If Gate Triggers)
+
+### Security Gate
+
+Load `secure-coding-cybersecurity` if the change touches any of:
+
+- Auth/session/permissions
+- User input handling or validation
+- SQL/ORM queries or dynamic filters
+- File paths/uploads
+- Secrets/tokens/credentials
+- Shell/command execution
+
+### Testing Gate
+
+Load `test-generator` if:
+
+- There are no tests for the changed behavior, or
+- Existing tests do not cover acceptance criteria, or
+- Regression risk is medium/high.
+
+### Consistency Gate
+
+Load `spec-analysis` and `requirement-checklist` if:
+
+- Requirements are ambiguous, or
+- Change spans multiple modules, or
+- Change modifies core domain behavior.
+
+### API Gate
+
+Load `api-design-principles` if API contracts/endpoints/schemas are added or modified.
+
+### UI Gate
+
+Load `interface-design` if dashboard/app UI behavior is introduced or changed.
+
+### Performance Gate
+
+Load `performance-optimizer` if:
+
+- The change affects hot paths, or
+- Latency/throughput targets exist, or
+- A performance regression is detected/suspected.
+
+### Context Scale Gate
+
+Load `project-index` and/or `context-synthesizer` if:
+
+- Codebase is large and discovery cost is high, or
+- Session is long and context drift appears.
+
+### Debug Gate
+
+Load `systematic-debugging` when blocked by non-trivial bugs or unstable behavior.
+
+---
+
+## Mandatory Quality Gates
+
+These gates are non-optional in `ac-lite`.
+
+### Gate A: Ready to Implement
+
+Before `openspec-apply-change`, all must be true:
+
+- Change exists and status is valid (`acfm spec status --change <name> --json`)
+- `tasks.md` exists with actionable checkboxes
+- Acceptance criteria are clear in artifacts
+- Required conditional skills (if triggered) were executed
+
+If any item fails: stop, resolve, then continue.
+
+### Gate B: Ready to Archive
+
+Before `openspec-archive-change`, all must be true:
+
+- `openspec-verify-change` completed
+- No CRITICAL findings remain
+- Relevant tests pass for changed behavior
+- Tasks are complete or explicitly accepted by user with warning
+
+If any item fails: stop, fix, re-verify.
+
+---
+
+## Lite Workflows
+
+### New Change (Default Path)
+
+1. Run `acfm-spec-workflow` checks (`acfm spec status --json`, init if needed).
+2. Create change with `openspec-new-change` (or `openspec-ff-change` if user requests speed).
+3. Build artifacts with `openspec-continue-change` until apply-ready.
+4. Evaluate conditional gates and load only triggered skills.
+5. Pass Gate A.
+6. Implement with `openspec-apply-change`.
+7. Verify with `openspec-verify-change`.
+8. Pass Gate B.
+9. Archive with `openspec-archive-change`.
+
+### Existing Change (Default Path)
+
+1. Confirm initialization and active changes.
+2. Select target change.
+3. Refresh artifact status.
+4. Evaluate conditional gates (only load what triggers).
+5. Pass Gate A.
+6. Implement.
+7. Verify.
+8. Pass Gate B.
+9. Archive.
+
+---
+
+## Operational Rules
+
+1. Do not load broad quality/documentation skills by default.
+2. Do not run optional skills "just in case".
+3. If risk increases during implementation, activate the matching conditional skill immediately.
+4. Prefer deterministic CLI checks over narrative assumptions.
+5. Keep outputs concise but auditable (show which gates passed/failed and why).
+
+---
+
+## Suggested Minimal Execution Template
+
+Use this structure in each run:
+
+1. **Change Context**
+   - Change name
+   - Current artifact progress
+
+2. **Triggered Gates**
+   - Security: pass/fail + reason
+   - Testing: pass/fail + reason
+   - Consistency/API/UI/Performance/Context/Debug: pass/fail + reason
+
+3. **Skills Loaded**
+   - Core: always list
+   - Conditional: list only triggered ones
+
+4. **Gate A Status**
+   - Ready to implement: yes/no
+
+5. **Implementation + Verify**
+   - What was implemented
+   - Verify findings summary
+
+6. **Gate B Status**
+   - Ready to archive: yes/no
+
+7. **Archive Result**
+   - Archive path and timestamp
+
+---
+
+## Token Strategy Summary
+
+`ac-lite` reduces cost by replacing "load everything first" with:
+
+- Mandatory core workflow only
+- Risk-gated skill expansion
+- Hard quality checkpoints at implementation and archive boundaries
+
+This preserves software quality while avoiding unnecessary instruction/context overhead.

package/framework/.agent/workflows/ac.md

@@ -42,6 +42,46 @@ If you attempt to proceed without completing a required step, you MUST STOP and
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
 | `acfm-spec-workflow` | **START HERE - MANDATORY** - Understand the spec-driven workflow, directory structure (.acfm/ vs openspec/), and CLI commands. Essential before using any OpenSpec skills. | Foundation | **ANYTHING ELSE** |
+| `acfm-memory` | **AUTONOMOUS MEMORY SYSTEM** - Persistent learning system that automatically saves important decisions, patterns, bugfixes. Use to recall context from previous changes and maintain knowledge across sessions. | Knowledge persistence | **AFTER ANY SIGNIFICANT WORK** |
+
+
+### Memory System (Automatic)
+
+The AC Framework includes an **autonomous memory system** that learns from your work:
+
+**What gets saved automatically:**
+- Architectural decisions from proposals/designs
+- Bugfix patterns and solutions
+- Performance optimizations
+- Refactoring techniques
+- Security fixes
+- API patterns and conventions
+
+**How to use memory:**
+```bash
+# Recall relevant context before starting work
+acfm memory recall "implementing authentication"
+
+# Search for specific patterns
+acfm memory search "JWT token refresh"
+
+# Get full context for current project
+acfm memory recall
+
+# View statistics
+acfm memory stats
+```
+
+**When the agent saves memory (automatic):**
+1. After completing proposal.md (saves architectural decisions)
+2. After fixing bugs (solutions are stored)
+3. After refactoring (techniques are recorded)
+4. After optimizations (performance insights)
+5. After any significant decision with confidence > 0.7
+
+**The agent will inform you:** "💾 Memory saved: [brief description]" when auto-saving occurs.
+
+**Privacy:** Content between `<private>...</private>` tags is automatically redacted before saving.
 
 ### OpenSpec Skills (The heart of the framework)