ac-framework 1.4.0 → 1.6.0

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

@@ -0,0 +1,261 @@
+**Fundamental Principle**: *"Quality over speed. Documentation before code. Planning before execution."*
+
+--- YOU SHOULD FOLLOW THIS EXACT WORKFLOW HERE, DONT SKIP STEPS, DONT CHANGE THE ORDER OF THE WORKFLOW, DONT SKIP SKILLS, DONT SKIP PHASES, DONT SKIP ANYTHING, JUST FOLLOW THE WORKFLOW EXACTLY AS IT IS WRITTEN HERE
+
+## 🛠️ Available Skills
+
+### Quality and Security Skills
+
+| Skill | Description | Primary Use |
+|-------|-------------|---------------|
+| `secure-coding-cybersecurity` | Detects and prevents security vulnerabilities (SQLi, XSS, command injection, hardcoded secrets). Follows OWASP Top 10 standards. | Secure code validation |
+| `code-maintainability` | Analyzes code maintainability: duplication, documentation, error handling, naming conventions, SOLID architecture, performance. | Refactoring and standards |
+| `error-handling-patterns` | Error handling patterns in multiple languages: exceptions, Result types, retry, circuit breaker, graceful degradation. | Application resilience |
+| `performance-optimizer` | Methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage). | Performance Engineering |
+| `test-generator` | Generate comprehensive test suites (Unit, Integration, E2E) ensuring requirements are met. | Test Driven Development |
+
+### SpecKit Consistency & Quality Skills
+
+| Skill | Description | Primary Use |
+|-------|-------------|---------------|
+| `project-constitution` | Manage the project's core principles and ensuring alignment. | Project Governance |
+| `requirement-checklist` | Generate quality control checklists for requirements (unit tests for specs). | Requirements Quality |
+| `spec-analysis` | Analyze consistency across Spec, Plan, and Tasks. | Consistency Check |
+| `spec-clarification` | Interactively clarify specific sections of the spec. | Ambiguity Resolution |
+
+### Planning and Design Skills
+
+| Skill | Description | Primary Use |
+|-------|-------------|---------------|
+| `brainstorming` | Generates ideas and questions decisions before implementing. Explores requirements, constraints, and success criteria. | Design and architecture |
+| `api-design-principles` | REST and GraphQL design principles: resources, endpoints, pagination, versioning, HATEOAS. | API design |
+| `interface-design` | Interface design (dashboards, admin panels, apps). NOT for landing pages/marketing. | UI design |
+
+### OpenSpec Skills (The heart of the framework)
+
+| Skill | Description | Primary Use |
+|-------|-------------|---------------|
+| `openspec-explore` | Exploration mode to investigate problems, map architecture, find integration points before implementing. | Pre-analysis |
+| `openspec-new-change` | Creates a new change with step-by-step workflow (proposal → specs → design → tasks). | Structured start |
+| `openspec-ff-change` | Fast-forward: creates all artifacts at once to start implementation quickly. | Quick start |
+| `openspec-continue-change` | Continues an existing change by creating the next artifact in the sequence. | Continue workflow |
+| `openspec-apply-change` | Implements tasks from a change (applies code according to specs and tasks). | Change execution |
+| `openspec-verify-change` | Verifies that implementation matches artifacts (specs, tasks, design). | Validation |
+| `openspec-archive-change` | Archives a completed change by moving it to `openspec/changes/archive/`. | Change closure |
+| `openspec-onboard` | Guided tutorial to learn OpenSpec with a complete example workflow. | Learning |
+| `openspec-sync-specs` | Synchronizes delta specs to main specs (intelligent merge). | Update specs |
+| `openspec-bulk-archive-change` | Archives multiple completed changes at once. | Bulk cleanup |
+
+### Documentation and Debugging Skills
+
+| Skill | Description | Primary Use |
+|-------|-------------|---------------|
+| `project-index` | Generates structured project documentation: structure analysis, domains, agent guides. | Indexing and context |
+| `sync-index` | Keep project documentation (`project-index` and sub-skills) in sync with codebase changes. | Documentation Sync |
+| `systematic-debugging` | Structured debugging in 4 phases: root cause investigation, pattern analysis, hypothesis, implementation. | Problem resolution |
+| `changelog-generator` | Creates automated changelogs from git commits, translating technical to user language. | Version history |
+| `skill-writer` | Guide to create new skills for Claude Code with correct structure and frontmatter. | Create new skills |
+
+---
+
+## 📍 IMPORTANT: How to Use Skills
+
+**Skills are loaded as tools, NOT CLI commands.**
+
+The skills listed above are located at `framework/.agent/skills/<skill-name>/SKILL.md`. When you need to use a skill:
+
+1. **The Agent automatically loads the skill file** - No CLI command needed
+2. **Read the SKILL.md file** to understand its instructions
+3. **Follow the skill's guidance** exactly as written
+4. **Skills provide structured workflows** for specific tasks
+
+**Do NOT use CLI commands like `acfm spec <command>` unless the skill specifically instructs you to.** OpenSpec skills guide you through their workflow via the SKILL.md content, not through CLI invocations.
+
+---
+
+## 🚀 Workflow: New Project
+
+When starting a project **from scratch**, follow this mandatory workflow:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           WORKFLOW: NEW PROJECT                                  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌─────────────────┐
+    │     START       │
+    └────────┬────────┘
+             │
+             ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 1: FOUNDATIONS & GOVERNANCE           │
+    │  1. project-constitution                     │
+    │     └─ Define core principles                │
+    │  2. secure-coding-cybersecurity              │
+    │     └─ Establish security guidelines         │
+    │  3. code-maintainability                     │
+    │     └─ Define quality standards              │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 2: CONTEXT & DISCOVERY                │
+    │  4. project-index                            │
+    │     └─ Document initial structure            │
+    │  5. openspec-explore                         │
+    │     └─ Explore target architecture           │
+    │  6. brainstorming                            │
+    │     └─ Generate ideas and architecture       │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 3: REQUIREMENTS & DESIGN              │
+    │  7. spec-clarification (CRITICAL)            │
+    │     └─ CLARIFY requirements first            │
+    │  8. openspec-new-change                      │
+    │     └─ Create proposal                       │
+    │  9. openspec-continue-change                 │
+    │     └─ Draft Specs, Design, Tasks            │
+    │  10. spec-analysis                           │
+    │     └─ Verify consistency                    │
+    │  11. requirement-checklist                   │
+    │     └─ "Unit test" the specs                 │
+    │  12. api-design-principles [IF APIs]         │
+    │     └─ Design REST/GraphQL APIs              │
+    │  13. interface-design [IF UI]                │
+    │     └─ Design dashboards/apps interface      │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 4: IMPLEMENTATION                     │
+    │  14. test-generator                          │
+    │     └─ TDD: Write tests first                │
+    │  15. openspec-apply-change                   │
+    │     └─ Implement code to pass tests          │
+    │  16. secure-coding-cybersecurity             │
+    │     └─ Audit code for security               │
+    │  17. error-handling-patterns                 │
+    │     └─ Verify robust error handling          │
+    │  18. performance-optimizer                   │
+    │     └─ Optimize critical paths               │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 5: VALIDATION & CLOSURE               │
+    │  19. systematic-debugging                    │
+    │     └─ Resolve any issues                    │
+    │  20. openspec-verify-change                  │
+    │     └─ Validate against specs                │
+    │  21. sync-index                              │
+    │     └─ Update project documentation          │
+    │  22. changelog-generator                     │
+    │     └─ Generate release notes                │
+    │  23. openspec-archive-change                 │
+    │     └─ Archive the change                    │
+    └──────────────────────────────────────────────┘
+```
+
+**Conditional Skills Notes:**
+- `[IF APIs]`: Use api-design-principles only if the project involves REST/GraphQL APIs
+- `[IF UI]`: Use interface-design only if the project has dashboards, admin panels, or apps
+
+---
+
+## 🔄 Workflow: Existing Project
+
+When working on an **existing codebase** (adding features, fixing bugs, refactoring):
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                        WORKFLOW: EXISTING PROJECT                                │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌─────────────────┐
+    │  START CHANGE   │
+    └────────┬────────┘
+             │
+             ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 1: CONTEXT & ANALYSIS                 │
+    │  1. project-index (if needed)                │
+    │     └─ Map current system                    │
+    │  2. openspec-explore                         │
+    │     └─ Deep dive into relevant modules       │
+    │  3. brainstorming                            │
+    │     └─ Ideate on feature/fix                 │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 2: DISCOVERY & CLARIFICATION          │
+    │  4. spec-clarification (CRITICAL)            │
+    │     └─ CLARIFY requirements first            │
+    │  5. openspec-new-change                      │
+    │     └─ Initialize change artifact            │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 3: DESIGN & PLANNING                  │
+    │  6. openspec-continue-change                 │
+    │     └─ Draft Specs, Design, Tasks            │
+    │  7. spec-analysis                            │
+    │     └─ Check consistency with existing       │
+    │  8. requirement-checklist                    │
+    │     └─ Validate requirements                 │
+    │  9. api-design-principles [IF APIs]          │
+    │     └─ Design API changes                    │
+    │  10. interface-design [IF UI]                │
+    │     └─ Design interface changes              │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 4: IMPLEMENTATION                     │
+    │  11. test-generator                          │
+    │     └─ Generate tests for new feature        │
+    │  12. openspec-apply-change                   │
+    │     └─ Implement code                        │
+    │  13. secure-coding-cybersecurity             │
+    │     └─ Audit new code                        │
+    │  14. error-handling-patterns                 │
+    │     └─ Verify error handling                 │
+    │  15. performance-optimizer                   │
+    │     └─ Ensure no perf degradation            │
+    └────────────────────┬─────────────────────────┘
+                         │
+                         ▼
+    ┌──────────────────────────────────────────────┐
+    │  PHASE 5: OPTIMIZATION & VERIFICATION        │
+    │  16. systematic-debugging                    │
+    │     └─ Fix regressions                       │
+    │  17. openspec-verify-change                  │
+    │     └─ Final verification                    │
+    │  18. sync-index (IMPORTANT)                  │
+    │     └─ Update docs with new changes          │
+    │  19. changelog-generator                     │
+    │     └─ Generate release notes                │
+    │  20. openspec-archive-change                 │
+    │     └─ Archive change                        │
+    └──────────────────────────────────────────────┘
+```
+
+**Conditional Skills Notes:**
+- `[IF APIs]`: Use api-design-principles only if modifying/creating REST/GraphQL APIs
+- `[IF UI]`: Use interface-design only if modifying dashboards, admin panels, or apps
+- `project-index`: Run only if you haven't indexed the project yet or need to refresh context
+
+---
+
+## 📝 Skill Loading Reference
+
+All skills are located in: `framework/.agent/skills/`
+
+To load a skill, read its SKILL.md file:
+- Example: Read `framework/.agent/skills/spec-clarification/SKILL.md` to use the clarification workflow
+- Example: Read `framework/.agent/skills/interface-design/SKILL.md` to use interface design principles
+
+**Remember**: Skills are documentation-based workflows, NOT CLI commands. Load them by reading the SKILL.md files.

package/framework/.agent/workflows/opsx-apply.md

@@ -13,13 +13,13 @@ Implement tasks from an OpenSpec change.
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run `acfm spec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
 
    Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
 
 2. **Check status to understand the schema**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
@@ -28,7 +28,7 @@ Implement tasks from an OpenSpec change.
 3. **Get apply instructions**
 
    ```bash
-   openspec instructions apply --change "<name>" --json
+   acfm spec instructions apply --change "<name>" --json
    ```
 
    This returns:

package/framework/.agent/workflows/opsx-archive.md

@@ -10,7 +10,7 @@ Archive a completed change in the experimental workflow.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -19,7 +19,7 @@ Archive a completed change in the experimental workflow.
 
 2. **Check artifact completion status**
 
-   Run `openspec status --change "<name>" --json` to check artifact completion.
+   Run `acfm spec status --change "<name>" --json` to check artifact completion.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
@@ -146,7 +146,7 @@ Target archive directory already exists.
 
 **Guardrails**
 - Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
+- Use artifact graph (acfm spec status --json) for completion checking
 - Don't block archive on warnings - just inform and confirm
 - Preserve .openspec.yaml when moving to archive (it moves with the directory)
 - Show clear summary of what happened

package/framework/.agent/workflows/opsx-bulk-archive.md

@@ -12,7 +12,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
 1. **Get active changes**
 
-   Run `openspec list --json` to get all active changes.
+   Run `acfm spec list --json` to get all active changes.
 
    If no active changes exist, inform user and stop.
 
@@ -29,7 +29,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
    For each selected change, collect:
 
-   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+   a. **Artifact status** - Run `acfm spec status --change "<name>" --json`
       - Parse `schemaName` and `artifacts` list
       - Note which artifacts are `done` vs other states
 

package/framework/.agent/workflows/opsx-continue.md

@@ -10,7 +10,7 @@ Continue working on a change by creating the next artifact.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Run `acfm spec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name
@@ -24,7 +24,7 @@ Continue working on a change by creating the next artifact.
 
 2. **Check current status**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to understand current state. The response includes:
    - `schemaName`: The workflow schema being used (e.g., "spec-driven")
@@ -47,7 +47,7 @@ Continue working on a change by creating the next artifact.
    - Pick the FIRST artifact with `status: "ready"` from the status output
    - Get its instructions:
      ```bash
-     openspec instructions <artifact-id> --change "<name>" --json
+     acfm spec instructions <artifact-id> --change "<name>" --json
      ```
    - Parse the JSON. The key fields are:
      - `context`: Project background (constraints for you - do NOT include in output)
@@ -72,7 +72,7 @@ Continue working on a change by creating the next artifact.
 
 4. **After creating an artifact, show progress**
    ```bash
-   openspec status --change "<name>"
+   acfm spec status --change "<name>"
    ```
 
 **Output**

package/framework/.agent/workflows/opsx-explore.md

@@ -83,7 +83,7 @@ You have full context of the OpenSpec system. Use it naturally, don't force it.
 
 At the start, quickly check what exists:
 ```bash
-openspec list --json
+acfm spec list --json
 ```
 
 This tells you:

package/framework/.agent/workflows/opsx-ff.md

@@ -19,13 +19,13 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
 2. **Create the change directory**
    ```bash
-   openspec new change "<name>"
+   acfm spec new "<name>"
    ```
    This creates a scaffolded change at `openspec/changes/<name>/`.
 
 3. **Get the artifact build order**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
@@ -40,7 +40,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
    a. **For each artifact that is `ready` (dependencies satisfied)**:
       - Get instructions:
         ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
+        acfm spec instructions <artifact-id> --change "<name>" --json
         ```
       - The instructions JSON includes:
         - `context`: Project background (constraints for you - do NOT include in output)
@@ -55,7 +55,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
       - Show brief progress: "✓ Created <artifact-id>"
 
    b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - After creating each artifact, re-run `acfm spec status --change "<name>" --json`
       - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
       - Stop when all `applyRequires` artifacts are done
 
@@ -65,7 +65,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
 5. **Show final status**
    ```bash
-   openspec status --change "<name>"
+   acfm spec status --change "<name>"
    ```
 
 **Output**
@@ -78,7 +78,7 @@ After completing all artifacts, summarize:
 
 **Artifact Creation Guidelines**
 
-- Follow the `instruction` field from `openspec instructions` for each artifact type
+- Follow the `instruction` field from `acfm spec instructions` for each artifact type
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
 - Use the `template` as a starting point, filling in based on context

package/framework/.agent/workflows/opsx-new.md

@@ -23,27 +23,27 @@ Start a new change using the experimental artifact-driven approach.
 
    **Use a different schema only if the user mentions:**
    - A specific schema name → use `--schema <name>`
-   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
+   - "show workflows" or "what workflows" → run `acfm spec schemas --json` and let them choose
 
    **Otherwise**: Omit `--schema` to use the default.
 
 3. **Create the change directory**
    ```bash
-   openspec new change "<name>"
+   acfm spec new "<name>"
    ```
    Add `--schema <name>` only if the user requested a specific workflow.
    This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
 
 4. **Show the artifact status**
    ```bash
-   openspec status --change "<name>"
+   acfm spec status --change "<name>"
    ```
    This shows which artifacts need to be created and which are ready (dependencies satisfied).
 
 5. **Get instructions for the first artifact**
    The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
    ```bash
-   openspec instructions <first-artifact-id> --change "<name>"
+   acfm spec instructions <first-artifact-id> --change "<name>"
    ```
    This outputs the template and context for creating the first artifact.
 

package/framework/.agent/workflows/opsx-onboard.md

@@ -11,11 +11,11 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t
 Before starting, check if OpenSpec is initialized:
 
 ```bash
-openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+acfm spec status --json 2>&1 || echo "NOT_INITIALIZED"
 ```
 
 **If not initialized:**
-> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`.
+> OpenSpec isn't set up in this project yet. Run `acfm spec init` first, then come back to `/opsx:onboard`.
 
 Stop here if not initialized.
 
@@ -161,7 +161,7 @@ Let me create one for our task.
 
 **DO:** Create the change with a derived kebab-case name:
 ```bash
-openspec new change "<derived-name>"
+acfm spec new "<derived-name>"
 ```
 
 **SHOW:**
@@ -230,7 +230,7 @@ Does this capture the intent? I can adjust before we save it.
 
 After approval, save the proposal:
 ```bash
-openspec instructions proposal --change "<name>" --json
+acfm spec instructions proposal --change "<name>" --json
 ```
 Then write the content to `openspec/changes/<name>/proposal.md`.
 
@@ -416,7 +416,7 @@ Archived changes become your project's decision history—you can always find th
 
 **DO:**
 ```bash
-openspec archive "<name>"
+acfm spec archive "<name>"
 ```
 
 **SHOW:**

package/framework/.agent/workflows/opsx-sync.md

@@ -12,7 +12,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show changes that have delta specs (under `specs/` directory).
 

package/framework/.agent/workflows/opsx-verify.md

@@ -10,7 +10,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   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.
@@ -20,7 +20,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
 2. **Check status to understand the schema**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
@@ -29,7 +29,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 3. **Get the change directory and load artifacts**
 
    ```bash
-   openspec instructions apply --change "<name>" --json
+   acfm spec instructions apply --change "<name>" --json
    ```
 
    This returns the change directory and context files. Read all available artifacts from `contextFiles`.