ac-framework 1.5.0 → 1.7.0

package/framework/.agent/skills/acfm-spec-workflow/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: acfm-spec-workflow
+description: Initialize and manage AC Framework spec-driven workflows using acfm CLI. Use when setting up spec workflows, checking project status, creating changes, or understanding the .acfm/ vs openspec/ directory structures. Essential first step before using any OpenSpec skills.
+---
+
+# AC Framework Spec-Driven Workflow
+
+Guide for initializing and managing spec-driven development workflows using the AC Framework CLI (`acfm`).
+
+## When to use this skill
+
+Use this skill when:
+- **Starting a new project** and need to initialize the spec workflow
+- **Working on an existing project** and need to check if specs are initialized
+- **Creating a new change/feature** using the spec-driven workflow
+- **Unsure whether to use `.acfm/` or `openspec/`** directories
+- **Need to understand CLI commands** for spec management
+- **Migrating from legacy openspec/ to new .acfm/ structure**
+
+## Quick start
+
+```bash
+# Check if project is initialized
+acfm spec status --json
+
+# Initialize new project (creates .acfm/)
+acfm spec init
+
+# Create a new change
+acfm spec new my-feature --json
+
+# Get instructions for next artifact
+acfm spec instructions proposal --change my-feature --json
+```
+
+## Directory Structure
+
+### NEW (Default): `.acfm/` directory
+
+```
+project-root/
+├── .acfm/                    # NEW: Default spec directory
+│   ├── config.yaml           # Project configuration
+│   ├── specs/                # Shared specs
+│   └── changes/              # Active changes
+│       ├── archive/          # Archived changes
+│       └── my-feature/       # Individual change
+│           ├── .openspec.yaml
+│           ├── proposal.md
+│           ├── design.md
+│           ├── tasks.md
+│           └── specs/
+```
+
+### LEGACY: `openspec/` directory
+
+```
+project-root/
+├── openspec/                 # LEGACY: Still fully supported
+│   ├── config.yaml
+│   ├── specs/
+│   └── changes/
+```
+
+**Priority**: CLI automatically uses `.acfm/` if it exists, otherwise falls back to `openspec/`.
+
+## Instructions
+
+### Step 1: Check initialization status
+
+Always start by checking if the project is initialized:
+
+```bash
+acfm spec status --json
+```
+
+**If not initialized** (`"initialized": false`):
+- Proceed to Step 2 to initialize
+
+**If initialized** (`"initialized": true`):
+- Note the `dirName` field (either `.acfm` or `openspec`)
+- Proceed to Step 3 to create changes
+
+### Step 2: Initialize the project
+
+For new projects:
+
+```bash
+acfm spec init
+```
+
+This creates:
+- `.acfm/config.yaml` - Project configuration
+- `.acmf/specs/` - Shared specifications
+- `.acfm/changes/` - Active changes directory
+
+**Legacy support**: If the project already has `openspec/`, it will be detected automatically. No need to migrate unless desired.
+
+### Step 3: Create a change
+
+```bash
+acfm spec new <change-name> --json
+```
+
+Example:
+```bash
+acfm spec new user-authentication --json
+```
+
+**Output**:
+```json
+{
+  "changeDir": "/project/.acfm/changes/user-authentication",
+  "schemaName": "spec-driven",
+  "artifacts": ["proposal", "specs", "design", "tasks"]
+}
+```
+
+### Step 4: Get instructions for artifacts
+
+Each artifact has specific instructions:
+
+```bash
+# Get instructions for proposal
+acfm spec instructions proposal --change <name> --json
+
+# Get instructions for design
+acfm spec instructions design --change <name> --json
+
+# Get instructions for tasks
+acfm spec instructions tasks --change <name> --json
+
+# Get apply instructions (when ready to implement)
+acfm spec instructions apply --change <name> --json
+```
+
+### Step 5: Check status
+
+Monitor progress:
+
+```bash
+# Status of specific change
+acfm spec status --change <name> --json
+
+# List all changes
+acfm spec list --json
+```
+
+### Step 6: Archive completed changes
+
+```bash
+acfm spec archive <change-name>
+```
+
+## CLI Command Reference
+
+### Initialization
+- `acfm spec init [--json]` - Initialize spec directory
+- `acfm spec status [--json]` - Check initialization status
+
+### Change Management
+- `acfm spec new <name> [--json]` - Create new change
+- `acfm spec list [--json]` - List all changes
+- `acfm spec status --change <name> [--json]` - Check change status
+- `acfm spec archive <name> [--json]` - Archive completed change
+
+### Instructions
+- `acfm spec instructions <artifact> --change <name> [--json]` - Get artifact instructions
+- `acfm spec schemas [--json]` - List available schemas
+- `acfm spec validate <name> [--json]` - Validate change structure
+
+## Common scenarios
+
+### Scenario: New project setup
+
+```bash
+# 1. Check status
+acfm spec status --json
+
+# 2. Initialize
+acfm spec init
+
+# 3. Create first change
+acfm spec new initial-setup --json
+
+# 4. Get proposal instructions
+acfm spec instructions proposal --change initial-setup --json
+```
+
+### Scenario: Legacy project (openspec/)
+
+```bash
+# CLI automatically detects openspec/ directory
+acfm spec status --json
+# Output: { "initialized": true, "dirName": "openspec", ... }
+
+# Create change in openspec/
+acfm spec new legacy-feature --json
+# Creates: openspec/changes/legacy-feature/
+```
+
+### Scenario: Mixed directories
+
+If both `.acfm/` and `openspec/` exist:
+- CLI uses `.acfm/` (higher priority)
+- Changes are created in `.acfm/changes/`
+
+To use `openspec/` temporarily:
+```bash
+mv .acfm/ .acfm-backup/
+# Now CLI will use openspec/
+```
+
+## Best practices
+
+1. **Always use CLI commands** - Don't manually create directories
+2. **Use `--json` flag** for programmatic parsing
+3. **Check initialization first** - Before creating changes
+4. **Let CLI handle paths** - Don't hardcode `.acfm/` or `openspec/`
+5. **Archive completed changes** - Keeps active list clean
+
+## Troubleshooting
+
+### "Spec system not initialized"
+
+```bash
+# Solution
+acfm spec init
+```
+
+### Changes not appearing
+
+```bash
+# Check which directory is being used
+acfm spec status --json
+# Look at "dirName" field
+
+# List both directories
+ls -la .acfm/changes/ 2>/dev/null || echo "No .acfm/"
+ls -la openspec/changes/ 2>/dev/null || echo "No openspec/"
+```
+
+### Wrong directory detected
+
+```bash
+# Force use of openspec/ by renaming .acfm/
+mv .acfm/ .acfm-backup/
+
+# Or force use of .acfm/ by renaming openspec/
+mv openspec/ openspec-backup/
+```
+
+## Requirements
+
+- AC Framework CLI (`acfm`) must be installed
+- Node.js >= 18.0.0
+
+## Compatibility
+
+- ✅ Works with both `.acfm/` (new) and `openspec/` (legacy)
+- ✅ All existing OpenSpec skills continue to work
+- ✅ No migration required for legacy projects
+- ✅ Optional migration path available
+
+## See also
+
+- Use `openspec-new-change` skill after initialization to create structured changes
+- Use `openspec-continue-change` to work on existing changes
+- Use `openspec-apply-change` to implement tasks

package/framework/.agent/skills/brainstorming/SKILL.md

@@ -1,54 +1,282 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+description: Generates comprehensive questions about decisions before implementing. Explores requirements, constraints, success criteria, edge cases, and hidden assumptions in a SINGLE comprehensive prompt. Use when starting any significant work to surface unknowns early.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "2.0"
 ---
 
-# Brainstorming Ideas Into Designs
+# Brainstorming - Comprehensive Question Generation
 
-## Overview
+Surface unknowns, challenge assumptions, and explore the problem space BEFORE committing to a solution.
 
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+## When to Use This Skill
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+Use this skill when:
+- Starting a new project or major feature
+- Facing ambiguous requirements
+- Need to explore multiple approaches
+- Want to identify risks early
+- Before creating any OpenSpec change
 
-## The Process
+**CRITICAL: This skill generates ALL questions in ONE prompt, not sequentially.**
 
-**Understanding the idea:**
-- Check out the current project state first (files, docs, recent commits)
-- Ask questions one at a time to refine the idea
-- Prefer multiple choice questions when possible, but open-ended is fine too
-- Only one question per message - if a topic needs more exploration, break it into multiple questions
-- Focus on understanding: purpose, constraints, success criteria
+---
+
+## Instructions
+
+### Step 1: Analyze the Context
+
+Read and understand:
+1. The user's stated goal/requirement
+2. Any existing project context from `project-index`
+3. Constraints mentioned or implied
+4. Success criteria (explicit or assumed)
+
+### Step 2: Generate Comprehensive Brainstorming Questions
+
+**⚠️ IMPORTANT: Generate ALL questions in a SINGLE comprehensive prompt.**
+
+Do NOT ask questions one by one. Instead, present a complete brainstorming document with ALL relevant questions organized by category.
+
+Structure your response as:
+
+```
+## 🧠 Brainstorming Analysis: [Feature/Project Name]
+
+### Context Summary
+[Brief summary of what you're building and why]
+
+### Category 1: Requirements & Scope
+Questions to clarify WHAT we're building:
+- Q1: [Specific question about requirements]
+- Q2: [Question about scope boundaries]
+- Q3: [Question about feature completeness]
+- ...
+
+### Category 2: Constraints & Limitations
+Questions about boundaries and restrictions:
+- Q1: [Technical constraint question]
+- Q2: [Time/budget constraint question]
+- Q3: [Regulatory/compliance question]
+- ...
+
+### Category 3: User Experience & Interface
+Questions about HOW users will interact:
+- Q1: [User flow question]
+- Q2: [Accessibility concern]
+- Q3: [Error handling UX question]
+- ...
+
+### Category 4: Technical Architecture
+Questions about implementation approach:
+- Q1: [Technology stack question]
+- Q2: [Integration point question]
+- Q3: [Scalability concern]
+- Q4: [Data model question]
+- ...
+
+### Category 5: Edge Cases & Failure Modes
+Questions about what could go wrong:
+- Q1: [Edge case scenario question]
+- Q2: [Failure recovery question]
+- Q3: [Security vulnerability question]
+- Q4: [Performance degradation scenario]
+- ...
+
+### Category 6: Success Criteria & Metrics
+Questions about how we measure success:
+- Q1: [Success metric question]
+- Q2: [Quality threshold question]
+- Q3: [User adoption question]
+- ...
+
+### Category 7: Dependencies & Blockers
+Questions about external factors:
+- Q1: [Third-party dependency question]
+- Q2: [Team/resource dependency]
+- Q3: [Upstream/downstream system question]
+- ...
+
+### Category 8: Alternative Approaches
+Questions exploring different solutions:
+- Q1: [Alternative technology question]
+- Q2: [Simpler approach question]
+- Q3: [Trade-off analysis question]
+- ...
+
+---
+
+## 🎯 Next Steps
+
+Please answer the questions above. Once clarified, we can proceed to:
+1. `openspec-new-change` - Create structured change
+2. `openspec-ff-change` - Fast-forward to implementation
+3. Continue brainstorming if needed
+
+**Your answers will shape the entire implementation approach.**
+```
+
+### Step 3: Wait for Comprehensive Answers
+
+After presenting ALL questions:
+- Wait for the user to answer them (may be partial or complete)
+- Ask follow-up questions ONLY if answers reveal new unknowns
+- Do NOT re-ask questions already answered
+
+### Step 4: Synthesize Insights
+
+Once you have answers:
+1. Summarize key decisions made
+2. Identify any remaining ambiguities
+3. Document assumptions being made
+4. Suggest the best path forward
+
+---
+
+## Question Categories Reference
 
-**Exploring approaches:**
-- Propose 2-3 different approaches with trade-offs
-- Present options conversationally with your recommendation and reasoning
-- Lead with your recommended option and explain why
+Always consider questions from these categories:
 
-**Presenting the design:**
-- Once you believe you understand what you're building, present the design
-- Break it into sections of 200-300 words
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
+**1. Requirements & Scope**
+- What exactly needs to be built?
+- What is explicitly OUT of scope?
+- Are there different user types with different needs?
+- What is the minimum viable version?
 
-## After the Design
+**2. Constraints & Limitations**
+- Technical stack constraints?
+- Time/deadline constraints?
+- Budget/resource constraints?
+- Regulatory/compliance requirements?
+- Legacy system constraints?
 
-**Documentation:**
-- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
-- Use elements-of-style:writing-clearly-and-concisely skill if available
-- Commit the design document to git
+**3. User Experience**
+- Who are the users?
+- What is their technical sophistication?
+- What devices/platforms will they use?
+- Accessibility requirements?
+- Localization needs?
 
-**Implementation (if continuing):**
-- Ask: "Ready to set up for implementation?"
-- Use superpowers:using-git-worktrees to create isolated workspace
-- Use superpowers:writing-plans to create detailed implementation plan
+**4. Technical Architecture**
+- Integration points with existing systems?
+- Data storage requirements?
+- Scalability expectations?
+- Security requirements?
+- Performance requirements (latency, throughput)?
+
+**5. Edge Cases & Failure Modes**
+- What happens when [X] fails?
+- How does the system handle invalid input?
+- What about concurrent access?
+- What's the behavior at scale limits?
+- Disaster recovery needs?
+
+**6. Success Metrics**
+- How do we know this is working?
+- What are the KPIs?
+- User satisfaction measures?
+- Technical performance thresholds?
+
+**7. Dependencies**
+- External APIs or services needed?
+- Other team dependencies?
+- Infrastructure requirements?
+- Third-party licenses or approvals?
+
+**8. Alternatives**
+- What simpler approaches exist?
+- What are the trade-offs?
+- Buy vs build decisions?
+- Short-term vs long-term considerations?
+
+---
+
+## Example Output
+
+**User says:** "Build a user authentication system"
+
+**Your brainstorming (SINGLE PROMPT):**
+
+```
+## 🧠 Brainstorming Analysis: User Authentication System
+
+### Context Summary
+Building an auth system for user login/signup. Critical security component affecting all users.
+
+### Category 1: Requirements & Scope
+- Q1: What authentication methods? (email/password, OAuth, SSO, magic links, 2FA?)
+- Q2: Do users need profiles, or just auth?
+- Q3: Session duration? Remember me feature?
+- Q4: Account recovery options?
+- Q5: Admin/moderator roles needed?
+
+### Category 2: Constraints & Limitations
+- Q6: Any compliance requirements? (GDPR, HIPAA, SOC2)
+- Q7: Password complexity requirements?
+- Q8: Rate limiting needs for brute force protection?
+
+### Category 3: User Experience
+- Q9: Login/signup flow preference? (modal, separate page, inline)
+- Q10: Error message style? (specific vs generic for security)
+- Q11: Email verification required before access?
+
+### Category 4: Technical Architecture
+- Q12: JWT vs session cookies vs other?
+- Q13: Database for user storage?
+- Q14: Password hashing algorithm? (bcrypt, Argon2)
+- Q15: Token refresh strategy?
+
+### Category 5: Edge Cases & Failure Modes
+- Q16: What if email provider is down during signup?
+- Q17: Handle concurrent login attempts from different devices?
+- Q18: Account lockout after failed attempts?
+- Q19: Session invalidation on password change?
+
+### Category 6: Success Criteria
+- Q20: Login success rate target?
+- Q21: Maximum acceptable login latency?
+- Q22: Security audit requirements?
+
+### Category 7: Dependencies
+- Q23: Email service provider? (SendGrid, AWS SES, etc.)
+- Q24: Existing user database to migrate?
+- Q25: Frontend framework constraints?
+
+### Category 8: Alternative Approaches
+- Q26: Use Auth0/Firebase Auth instead of building?
+- Q27: Start with simple email/pass, add OAuth later?
+```
+
+---
+
+## Guardrails
+
+- **ALWAYS ask ALL questions in ONE prompt** - Never sequential
+- **Be thorough** - Better to ask too much than miss critical context
+- **Organize clearly** - Categories help the user answer systematically
+- **Wait for answers** - Don't proceed until user responds
+- **Synthesize** - After answers, provide clear summary and recommendation
+- **No implementation** - This is thinking only, no code yet
+
+---
+
+## Integration with OpenSpec
+
+After brainstorming is complete:
+
+1. Summarize decisions made
+2. Recommend next step:
+   - `openspec-new-change` for structured approach
+   - `openspec-ff-change` if ready to fast-forward
+3. Include brainstorming insights in the change proposal
+
+---
 
-## Key Principles
+## Requirements
 
-- **One question at a time** - Don't overwhelm with multiple questions
-- **Multiple choice preferred** - Easier to answer than open-ended when possible
-- **YAGNI ruthlessly** - Remove unnecessary features from all designs
-- **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design in sections, validate each
-- **Be flexible** - Go back and clarify when something doesn't make sense
+- Understanding of the problem domain
+- Ability to think systematically about edge cases
+- Familiarity with common software architecture patterns
+- Knowledge of security, performance, and UX best practices