ac-framework 1.5.0 → 1.7.0

package/framework/.claude/commands/opsx/ac.md

@@ -1,57 +1,138 @@
- **Fundamental Principle**: *"Quality over speed. Documentation before code. Planning before execution."*
+**Fundamental Principle**: *"Quality over speed. Documentation before code. Planning before execution."*
+
+--- ⚠️ **CRITICAL: ZERO SKIP POLICY** ⚠️ ---
+
+**YOU CANNOT SKIP ANY STEP. YOU CANNOT SKIP ANY SKILL. YOU CANNOT SKIP ANY PHASE.**
+
+If you attempt to proceed without completing a required step, you MUST STOP and complete it first.
+
 ---
 
 ## 🛠️ 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 |
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `secure-coding-cybersecurity` | Detects and prevents security vulnerabilities (SQLi, XSS, command injection, hardcoded secrets). Follows OWASP Top 10 standards. | Secure code validation | `code-maintainability` |
+| `code-maintainability` | Analyzes code maintainability: duplication, documentation, error handling, naming conventions, SOLID architecture, performance. | Refactoring and standards | `project-constitution` |
+| `error-handling-patterns` | Error handling patterns in multiple languages: exceptions, Result types, retry, circuit breaker, graceful degradation. | Application resilience | `secure-coding-cybersecurity` |
+| `performance-optimizer` | Methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage). | Performance Engineering | After Implementation |
+| `test-generator` | Generate comprehensive test suites (Unit, Integration, E2E) ensuring requirements are met. | Test Driven Development | `openspec-continue-change` |
+
+### SpecKit Consistency & Quality Skills
+
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `project-constitution` | Manage the project's core principles and ensuring alignment. | Project Governance | **PHASE 1 START** |
+| `requirement-checklist` | Generate quality control checklists for requirements (unit tests for specs). | Requirements Quality | `spec-clarification` |
+| `spec-analysis` | Analyze consistency across Spec, Plan, and Tasks. | Consistency Check | `openspec-continue-change` |
+| `spec-clarification` | Interactively clarify specific sections of the spec. | Ambiguity Resolution | `openspec-new-change` |
 
 ### 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 |
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `brainstorming` | Generates ALL questions at once about decisions before implementing. Explores requirements, constraints, and success criteria in a SINGLE comprehensive prompt. | Design and architecture | `openspec-explore` |
+| `api-design-principles` | REST and GraphQL design principles: resources, endpoints, pagination, versioning, HATEOAS. | API design | `spec-clarification` [IF APIs] |
+| `interface-design` | Interface design (dashboards, admin panels, apps). NOT for landing pages/marketing. | UI design | `spec-clarification` [IF UI] |
+
+### AC Framework Core Skills
+
+| 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** |
 
 ### 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 |
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `openspec-explore` | Exploration mode to investigate problems, map architecture, find integration points before implementing. | Pre-analysis | `acfm-spec-workflow` |
+| `openspec-new-change` | Creates a new change with step-by-step workflow (proposal → specs → design → tasks). | Structured start | `brainstorming` |
+| `openspec-ff-change` | Fast-forward: creates all artifacts at once to start implementation quickly. | Quick start | `brainstorming` |
+| `openspec-continue-change` | Continues an existing change by creating the next artifact in the sequence. | Continue workflow | `openspec-new-change` OR `microtask-decomposition` |
+| `openspec-apply-change` | Implements tasks from a change (applies code according to specs and tasks). | Change execution | `test-generator` |
+| `openspec-verify-change` | Verifies that implementation matches artifacts (specs, tasks, design). | Validation | `openspec-apply-change` |
+| `openspec-archive-change` | Archives a completed change by moving it to `{specDir}/changes/archive/`. | Change closure | `openspec-verify-change` |
+| `openspec-onboard` | Guided tutorial to learn OpenSpec with a complete example workflow. | Learning | `acfm-spec-workflow` |
+| `openspec-sync-specs` | Synchronizes delta specs to main specs (intelligent merge). | Update specs | `openspec-verify-change` |
+| `openspec-bulk-archive-change` | Archives multiple completed changes at once. | Bulk cleanup | `openspec-verify-change` |
 
 ### Documentation and Debugging Skills
 
-| Skill | Description | Primary Use |
-|-------|-------------|---------------|
-| `project-index` | Generates structured project documentation: structure analysis, domains, agent guides. | Indexing and context |
-| `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 |
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `project-index` | Generates structured project documentation: structure analysis, domains, agent guides. | Indexing and context | `project-constitution` |
+| `sync-index` | Keep project documentation (`project-index` and sub-skills) in sync with codebase changes. | Documentation Sync | `openspec-apply-change` |
+| `systematic-debugging` | Structured debugging in 4 phases: root cause investigation, pattern analysis, hypothesis, implementation. | Problem resolution | When bugs found |
+| `changelog-generator` | Creates automated changelogs from git commits, translating technical to user language. | Version history | `openspec-archive-change` |
+| `skill-writer` | Guide to create new skills for Claude Code with correct structure and frontmatter. | Create new skills | Anytime |
+| `vercel-react-best-practices` | React and Next.js performance optimization guidelines from Vercel Engineering. | React/Next.js optimization | [IF REACT] |
+
+### AC Framework Enhancement Skills
+
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `microtask-decomposition` | **LEVEL 2+ DECOMPOSITION** - Use when a single task from tasks.md is still too complex (affects 3+ files or requires multiple logic blocks). Breaks tasks into MICROTASKS (1 file/function each) for granular implementation. NOT for initial task breakdown. | Microtask planning & delegation | `openspec-continue-change` |
+| `testing-qa` | Automate generation and maintenance of unit, integration, and E2E tests; generate test data and debugging. | Quality assurance | `openspec-apply-change` |
+| `code-review` | Review generated code for style, security, and architecture issues; suggest refactorings and performance improvements. | Code quality & security | `openspec-apply-change` |
+| `documentation` | Generate clear documentation for each task: technical descriptions, architecture diagrams, usage guides. | Documentation & communication | `openspec-verify-change` |
+| `research-retrieval` | Search external documentation (web pages, API docs, papers) and generate useful summaries for development. | Research & context gathering | `openspec-explore` |
+| `context-synthesizer` | Manage memory in long projects and summarize current state to prevent agent context loss. | Memory & context management | `project-constitution` |
+| `ci-deploy` | Automate continuous integration, deployment, and post-deployment verification of developed solutions. | CI/CD automation | `openspec-verify-change` |
+
+---
+
+## 📍 CRITICAL: How to Use Skills - ZERO SKIP POLICY
+
+### ⛔ BLOCKING RULES - YOU CANNOT PROCEED WITHOUT THESE:
+
+**Rule 1: Phase Completion Checkpoint**
+After EACH phase, you MUST confirm completion:
+```
+╔══════════════════════════════════════════════════════════╗
+║  ⚠️  PHASE [X] COMPLETION CHECKPOINT                      ║
+╠══════════════════════════════════════════════════════════╣
+║  Have you COMPLETED ALL skills in Phase [X]?              ║
+║  [ ] Yes - I have read and executed every skill           ║
+║  [ ] No - I need to go back                               ║
+╚══════════════════════════════════════════════════════════╝
+```
+**IF NO: STOP. Go back and complete missing skills.**
+
+**Rule 2: Skill Dependency Chain**
+Each skill table above shows "Required Before". You CANNOT use a skill until its dependency is satisfied.
+
+**Rule 3: Output Verification**
+Before proceeding to next phase, verify you have these outputs:
+
+| Phase | Required Outputs | Check |
+|-------|-----------------|-------|
+| Phase 0 | `acfm spec status` shows initialized | [ ] |
+| Phase 1 | project-constitution.md defined | [ ] |
+| Phase 2 | project-index.md exists, exploration notes | [ ] |
+| Phase 3 | proposal.md, specs/, design.md, tasks.md | [ ] |
+| Phase 4 | Tests written, code implemented, tasks marked complete | [ ] |
+| Phase 5 | Verification passed, docs updated, change archived | [ ] |
+
+**Rule 4: Pre-Implementation Safety Check**
+Before `openspec-apply-change`, ALL must be TRUE:
+- [ ] tasks.md exists and has checkboxes
+- [ ] All tests from `test-generator` are written
+- [ ] design.md has been reviewed
+- [ ] spec-analysis shows consistency
+
+**IF ANY IS FALSE: STOP. Complete missing items.**
 
 ---
 
 ## 🚀 Workflow: New Project
 
-When starting a project **from scratch**, follow this mandatory workflow:
+When starting a project **from scratch**, follow this **MANDATORY** workflow:
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────────┐
-│                           WORKFLOW: NEW PROJECT                                  │
+│                    ⚠️  WORKFLOW: NEW PROJECT - ZERO SKIP  ⚠️                    │
 └─────────────────────────────────────────────────────────────────────────────────┘
 
     ┌─────────────────┐
@@ -59,240 +140,307 @@ When starting a project **from scratch**, follow this mandatory workflow:
     └────────┬────────┘
              │
              ▼
-    ┌──────────────────────────────────────────────┐
-    │  PHASE 1: FOUNDATIONS (Mandatory)            │
-    │                                              │
-    │  1. secure-coding-cybersecurity              │
-    │     └─ Establish security guidelines         │
-    │                                              │
-    │  2. code-maintainability                     │
-    │     └─ Define quality standards              │
-    │                                              │
-    │  3. brainstorming                            │
-    │     └─ Architecture and design decisions     │
-    └────────────────────┬─────────────────────────┘
-                         │
+    ╔══════════════════════════════════════════════╗
+    ║  ☠️  PHASE 0: AC FRAMEWORK SETUP (REQUIRED)   ║
+    ║  BLOCKING: Cannot proceed without this       ║
+    ╠══════════════════════════════════════════════╣
+    ║  1. acfm-spec-workflow                       ║
+    ║     └─ **ALWAYS START HERE**                 ║
+    ║     └─ Understand .acfm/ vs openspec/        ║
+    ║     └─ Learn CLI commands and workflow       ║
+    ║     └─ Check project initialization status   ║
+    ║     └─ RUN: acfm spec init (if needed)       ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║
+                         ║ ⛔ CHECKPOINT: Phase 0 Complete?
+                         ║    [ ] acfm spec status shows "initialized": true
+                         ║
+                         ║ YES ▼
                          ▼
-    ┌──────────────────────────────────────────────┐
-    │  PHASE 2: SPECIFICATION (Mandatory)          │
-    │                                              │
-    │  4. openspec-new-change                      │
-    │     └─ Create change with proposal           │
-    │                                              │
-    │  5. openspec-continue-change                 │
-    │     └─ Create specs, design, tasks           │
-    │        (or use openspec-ff-change)           │
-    └────────────────────┬─────────────────────────┘
-                         │
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 1: FOUNDATIONS & GOVERNANCE           ║
+    ╠══════════════════════════════════════════════╣
+    ║  1. project-constitution                     ║
+    ║     └─ Define core principles                ║
+    ║  2. secure-coding-cybersecurity              ║
+    ║     └─ Establish security guidelines         ║
+    ║  3. code-maintainability                     ║
+    ║     └─ Define quality standards              ║
+    ║  4. vercel-react-best-practices [IF REACT]   ║
+    ║     └─ Apply React/Next.js best practices    ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║
+                         ║ ⛔ CHECKPOINT: Phase 1 Complete?
+                         ║    [ ] project-constitution defined
+                         ║    [ ] Security guidelines established
+                         ║    [ ] Quality standards set
+                         ║
+                         ║ YES ▼
                          ▼
-    ┌──────────────────────────────────────────────┐
-    │  PHASE 3: IMPLEMENTATION                     │
-    │                                              │
-    │  6. openspec-apply-change                    │
-    │     └─ Implement the tasks                   │
-    └────────────────────┬─────────────────────────┘
-                         │
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 2: CONTEXT & DISCOVERY                ║
+    ╠══════════════════════════════════════════════╣
+    ║  5. context-synthesizer                      ║
+    ║     └─ Initialize memory and context state   ║
+    ║  6. project-index                            ║
+    ║     └─ Document initial structure            ║
+    ║  7. research-retrieval                       ║
+    ║     └─ Gather external documentation         ║
+    ║  8. openspec-explore                         ║
+    ║     └─ Explore target architecture           ║
+    ║  9. brainstorming                            ║
+    ║     └─ Generate ALL questions in ONE prompt  ║
+    ║     └─ Surface hidden assumptions            ║
+    ║     └─ Challenge constraints                 ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║
+                         ║ ⛔ CHECKPOINT: Phase 2 Complete?
+                         ║    [ ] project-index.md exists
+                         ║    [ ] Exploration notes documented
+                         ║    [ ] Brainstorming questions answered
+                         ║
+                         ║ YES ▼
                          ▼
-    ┌──────────────────────────────────────────────┐
-    │  PHASE 4: VALIDATION AND CLOSURE             │
-    │                                              │
-    │  7. systematic-debugging                     │
-    │     └─ Verify no errors                      │
-    │                                              │
-    │  8. openspec-verify-change                   │
-    │     └─ Validate against specs                │
-    │                                              │
-    │  9. changelog-generator                      │
-    │     └─ Generate in changelogs/by-ai/         │
-    │                                              │
-    │  10. openspec-archive-change                 │
-    │      └─ Archive the change                   │
-    └──────────────────────────────────────────────┘
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 3: REQUIREMENTS & DESIGN              ║
+    ╠══════════════════════════════════════════════╣
+    ║  10. spec-clarification (CRITICAL)           ║
+    ║      └─ CLARIFY requirements first           ║
+    ║  11. openspec-new-change                     ║
+    ║      └─ Create proposal                      ║
+    ║  12. microtask-decomposition                 ║
+    ║      └─ ONLY if task is still too complex    ║
+    ║      └─ Break into MICROTASKS (1 file each)  ║
+    ║  13. openspec-continue-change                ║
+    ║      └─ Draft Specs, Design, Tasks           ║
+    ║  14. spec-analysis                           ║
+    ║      └─ Verify consistency                   ║
+    ║  15. requirement-checklist                   ║
+    ║      └─ "Unit test" the specs                ║
+    ║  16. api-design-principles [IF APIs]         ║
+    ║      └─ Design REST/GraphQL APIs             ║
+    ║  17. interface-design [IF UI]                ║
+    ║      └─ Design dashboards/apps interface     ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║
+                         ║ ⛔ CHECKPOINT: Phase 3 Complete?
+                         ║    [ ] proposal.md created
+                         ║    [ ] specs/ directory with specs
+                         ║    [ ] design.md written
+                         ║    [ ] tasks.md with checkboxes
+                         ║    [ ] spec-analysis passed
+                         ║
+                         ║ YES ▼
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 4: IMPLEMENTATION                     ║
+    ╠══════════════════════════════════════════════╣
+    ║  ☠️  SAFETY CHECK - ALL MUST BE TRUE:        ║
+    ║  [ ] tasks.md exists                         ║
+    ║  [ ] Tests from test-generator written       ║
+    ║  [ ] design.md reviewed                      ║
+    ║  [ ] spec-analysis shows consistency         ║
+    ╠══════════════════════════════════════════════╣
+    ║  18. test-generator                          ║
+    ║      └─ TDD: Write tests first               ║
+    ║  19. openspec-apply-change                   ║
+    ║      └─ Implement code to pass tests         ║
+    ║  20. testing-qa                              ║
+    ║      └─ Automate test maintenance            ║
+    ║  21. code-review                             ║
+    ║      └─ Review for style/security/arch       ║
+    ║  22. secure-coding-cybersecurity             ║
+    ║      └─ Audit code for security              ║
+    ║  23. error-handling-patterns                 ║
+    ║      └─ Verify robust error handling         ║
+    ║  24. performance-optimizer                   ║
+    ║      └─ Optimize critical paths              ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║
+                         ║ ⛔ CHECKPOINT: Phase 4 Complete?
+                         ║    [ ] All tasks in tasks.md marked [x]
+                         ║    [ ] Tests passing
+                         ║    [ ] Code reviewed
+                         ║    [ ] Security audited
+                         ║
+                         ║ YES ▼
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 5: VALIDATION & CLOSURE               ║
+    ╠══════════════════════════════════════════════╣
+    ║  25. systematic-debugging                    ║
+    ║      └─ Resolve any issues                   ║
+    ║  26. openspec-verify-change                  ║
+    ║      └─ Validate against specs               ║
+    ║  27. documentation                           ║
+    ║      └─ Generate technical docs & diagrams   ║
+    ║  28. sync-index                              ║
+    ║      └─ Update project documentation         ║
+    ║  29. changelog-generator                     ║
+    ║      └─ Generate release notes               ║
+    ║  30. ci-deploy                               ║
+    ║      └─ Deploy and verify solution           ║
+    ║  31. openspec-archive-change                 ║
+    ║      └─ Archive the change                   ║
+    ╚══════════════════════════════════════════════╝
 ```
 
-### Phase Descriptions - New Project
-
-| Phase | Skill | Description | Expected Output |
-|------|-------|-------------|-----------------|
-| 1 | `secure-coding-cybersecurity` | Establish security guidelines: input validation, sanitization, injection prevention, secrets handling | `.agents/security-guidelines.md` |
-| 2 | `code-maintainability` | Define conventions: naming, folder structure, design patterns, DRY, testing | `.agents/maintainability-rules.md` |
-| 3 | `brainstorming` | Generate architecture ideas, question approach, explore alternatives | `.agents/architecture-decisions.md` |
-| 4 | `openspec-new-change` | Create change with proposal (why, what changes, capabilities) | `openspec/changes/<name>/proposal.md` |
-| 5 | `openspec-continue-change` | Create specs (WHEN/THEN requirements), design (technical decisions), tasks (checklist) | Complete OpenSpec artifacts |
-| 6 | `openspec-apply-change` | Implement code according to specs and tasks | Functional code |
-| 7 | `systematic-debugging` | Structured debugging: investigate root cause, don't guess | Validation report |
-| 8 | `openspec-verify-change` | Verify completeness, correctness, and coherence | Verification report |
-| 9 | `changelog-generator` | Document changes in user language | `changelogs/by-ai/[date]-[feature].md` |
-| 10 | `openspec-archive-change` | Move change to archive with date | `openspec/changes/archive/YYYY-MM-DD-<name>/` |
+**Conditional Skills Notes:**
+- `[IF REACT]`: Use vercel-react-best-practices only if the project uses React or Next.js
+- `[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
+- `microtask-decomposition`: Use ONLY when a single task from tasks.md is still too complex (3+ files). NOT for initial breakdown.
 
 ---
 
-## 🔍 Workflow: Existing Project
+## 🔄 Workflow: Existing Project
 
-When working on an **already created** project that does NOT have `.md` documentation files:
+When working on an **existing codebase** (adding features, fixing bugs, refactoring):
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────────┐
-│                        WORKFLOW: EXISTING PROJECT (NO DOCS)                      │
+│                  ⚠️  WORKFLOW: EXISTING PROJECT - ZERO SKIP  ⚠️                  │
 └─────────────────────────────────────────────────────────────────────────────────┘
 
-    ┌─────────────────────────────────────────────────────────────────────────┐
-    │                                                                          │
-    │   ⚠️  CHECK: No documentation .md files exist in                         │
-    │       .agents/ or openspec/                                              │
-    │                                                                          │
-    └────────────────────────────────────────────────────┬─────────────────────┘
-                                                         │
-                                                         ▼
-    ┌─────────────────────────────────────────────────────────────────────────┐
-    │                                                                          │
-    │   🔄 STEP 0: project-index                                               │
-    │   Generate complete documentation for existing project                   │
-    │   ├─ Analyze folder structure                                            │
-    │   ├─ Identify domains (UI, Backend, DB, etc.)                            │
-    │   ├─ Create specific sub-skills per domain                               │
-    │   └─ Generate agent-guidance files                                       │
-    │                                                                          │
-    │   Output:                                                                │
-    │   ├─ .agents/project-index.md                                            │
-    │   ├─ .agents/agent-<domain>.md (in each folder)                          │
-    │   └─ .claude/skills/project-index-<domain>/SKILL.md                      │
-    │                                                                          │
-    └─────────────────────────────────────────────────────────────────────────┘
+    ┌─────────────────┐
+    │  START CHANGE   │
+    └────────┬────────┘
+             │
+             ▼
+    ╔══════════════════════════════════════════════╗
+    ║  ☠️  PHASE 0: AC FRAMEWORK SETUP (REQUIRED)   ║
+    ║  BLOCKING: Cannot proceed without this       ║
+    ╠══════════════════════════════════════════════╣
+    ║  1. acfm-spec-workflow                       ║
+    ║     └─ **ALWAYS START HERE**                 ║
+    ║     └─ Verify project initialization         ║
+    ║     └─ Check existing changes                ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║
+                         ║ ⛔ CHECKPOINT: Phase 0 Complete?
+                         ║
+                         ║ YES ▼
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 1: CONTEXT & ANALYSIS                 ║
+    ╠══════════════════════════════════════════════╣
+    ║  2. context-synthesizer                      ║
+    ║     └─ Load memory and context state         ║
+    ║  3. project-index (if needed)                ║
+    ║     └─ Map current system                    ║
+    ║  4. research-retrieval                       ║
+    ║     └─ Gather external documentation         ║
+    ║  5. openspec-explore                         ║
+    ║     └─ Deep dive into relevant modules       ║
+    ║  6. brainstorming                            ║
+    ║     └─ ALL questions in ONE prompt           ║
+    ║     └─ Ideate on feature/fix                 ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║ ⛔ CHECKPOINT
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 2: DISCOVERY & CLARIFICATION          ║
+    ╠══════════════════════════════════════════════╣
+    ║  7. spec-clarification (CRITICAL)            ║
+    ║     └─ CLARIFY requirements first            ║
+    ║  8. openspec-new-change                      ║
+    ║     └─ Initialize change artifact            ║
+    ║  9. microtask-decomposition                  ║
+    ║     └─ If task too complex                   ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║ ⛔ CHECKPOINT
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 3: DESIGN & PLANNING                  ║
+    ╠══════════════════════════════════════════════╣
+    ║  10. openspec-continue-change                ║
+    ║      └─ Draft Specs, Design, Tasks           ║
+    ║  11. spec-analysis                           ║
+    ║      └─ Check consistency with existing      ║
+    ║  12. requirement-checklist                   ║
+    ║      └─ Validate requirements                ║
+    ║  13. api-design-principles [IF APIs]         ║
+    ║      └─ Design API changes                   ║
+    ║  14. interface-design [IF UI]                ║
+    ║      └─ Design interface changes             ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║ ⛔ CHECKPOINT
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 4: IMPLEMENTATION                     ║
+    ╠══════════════════════════════════════════════╣
+    ║  ☠️  SAFETY CHECK REQUIRED                   ║
+    ╠══════════════════════════════════════════════╣
+    ║  15. test-generator                          ║
+    ║      └─ Generate tests for new feature       ║
+    ║  16. openspec-apply-change                   ║
+    ║      └─ Implement code                       ║
+    ║  17. testing-qa                              ║
+    ║      └─ Automate test maintenance            ║
+    ║  18. code-review                             ║
+    ║      └─ Review for style/security/arch       ║
+    ║  19. secure-coding-cybersecurity             ║
+    ║      └─ Audit new code                       ║
+    ║  20. error-handling-patterns                 ║
+    ║      └─ Verify error handling                ║
+    ║  21. performance-optimizer                   ║
+    ║      └─ Ensure no perf degradation           ║
+    ╚════════════════════╬═════════════════════════╝
+                         ║ ⛔ CHECKPOINT
+                         ▼
+    ╔══════════════════════════════════════════════╗
+    ║  PHASE 5: OPTIMIZATION & VERIFICATION        ║
+    ╠══════════════════════════════════════════════╣
+    ║  22. systematic-debugging                    ║
+    ║      └─ Fix regressions                      ║
+    ║  23. openspec-verify-change                  ║
+    ║      └─ Final verification                   ║
+    ║  24. documentation                           ║
+    ║      └─ Generate technical docs & diagrams   ║
+    ║  25. sync-index (IMPORTANT)                  ║
+    ║      └─ Update docs with new changes         ║
+    ║  26. changelog-generator                     ║
+    ║      └─ Generate release notes               ║
+    ║  27. ci-deploy                               ║
+    ║      └─ Deploy and verify solution           ║
+    ║  28. openspec-archive-change                 ║
+    ║      └─ Archive change                       ║
+    ╚══════════════════════════════════════════════╝
 ```
 
-### Post-Indexing
-
-Once the project is indexed, continue with the [Changes Workflow](#-workflow-changesiterations).
+**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
 
 ---
 
-## 🔄 Workflow: Changes/Iterations
+## 📝 Skill Loading Reference
 
-For **each change or new feature** in an already documented project:
+All skills are located in: `skills/`
 
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                           WORKFLOW: CHANGES AND ITERATIONS                       │
-└─────────────────────────────────────────────────────────────────────────────────┘
+To load a skill, read its SKILL.md file:
+- Example: Read `skills/spec-clarification/SKILL.md` to use the clarification workflow
+- Example: Read `skills/interface-design/SKILL.md` to use interface design principles
 
-    ┌─────────────────────────┐
-    │   START CHANGE          │
-    └────────┬────────────────┘
-             │
-             ▼
-    ┌─────────────────────────┐     ┌──────────────────────────────────────────┐
-    │  1. openspec-explore    │────▶│  2. brainstorming                        │
-    │  (Explore current       │     │  (Based on exploration:                  │
-    │   code and structure)   │     │   - Generate ideas                       │
-    └─────────────────────────┘     │   - Suggest improvements                 │
-                                    │   - Ask key questions to user)           │
-                                    └─────────────────┬────────────────────────┘
-                                                      │
-                                                      ▼
-    ┌─────────────────────────┐     ┌──────────────────────────────────────────┐
-    │  3. openspec-new        │────▶│  4. openspec-continue / ff               │
-    │  (Create specification  │     │  (Create specs, design, tasks)           │
-    │   for change/feature)   │     └─────────────────┬────────────────────────┘
-    └─────────────────────────┘                       │
-                                                      ▼
-    ┌─────────────────────────┐     ┌──────────────────────────────────────────┐
-    │  5. openspec-apply      │────▶│  6. systematic-debugging                 │
-    │  (Implement changes     │     │  (Verify no errors,                      │
-    │   according to tasks)   │     │   validate patterns)                     │
-    └─────────────────────────┘     └─────────────────┬────────────────────────┘
-                                                      │
-                                                      ▼
-    ┌─────────────────────────┐     ┌──────────────────────────────────────────┐
-    │  7. openspec-verify     │────▶│  8. changelog-generator                  │
-    │  (Verify against        │     │  (Generate change record                 │
-    │   specs and design)     │     │   in changelogs/by-ai/)                  │
-    └─────────────────────────┘     └─────────────────┬────────────────────────┘
-                                                      │
-                                                      ▼
-    ┌─────────────────────────┐     ┌──────────────────────────────────────────┐
-    │  9. openspec-archive    │────▶│  10. openspec-sync-specs (optional)      │
-    │  (Archive completed     │     │  (Sync specs to main)                    │
-    │   change)               │     └──────────────────────────────────────────┘
-    └─────────────────────────┘
-                                                      │
-                                                      ▼
-    ┌─────────────────────────────────────────────────────────────────────────┐
-    │                                                                          │
-    │   ✅ CHANGE COMPLETED AND DOCUMENTED                                    │
-    │                                                                          │
-    └─────────────────────────────────────────────────────────────────────────┘
-```
+### ⛔ MANDATORY SKILL EXECUTION CHECKLIST
 
-### Phase Descriptions - Changes/Iterations
-
-| Phase | Skill | Description | Required Input | Expected Output |
-|------|-------|-------------|-----------------|-----------------|
-| 1 | `openspec-explore` | Analyze current code state, identify dependencies and modification points | Change request context | Impact report in `.agents/exploration-report.md` |
-| 2 | `brainstorming` | Generate ideas based on exploration, suggest alternatives, ask user questions | Exploration report | `.agents/brainstorming-session.md` with decisions |
-| 3 | `openspec-new-change` | Create change container with initial proposal | Brainstorming decisions | `openspec/changes/<name>/proposal.md` |
-| 4 | `openspec-continue-change` or `openspec-ff-change` | Create specs, design, and tasks | Approved proposal | Complete OpenSpec artifacts |
-| 5 | `openspec-apply-change` | Implement tasks as described | Tasks ready | Modified code following specs |
-| 6 | `systematic-debugging` | Validate no errors, verify applied patterns | Modified code | Validation report in `.agents/debug-report.md` |
-| 7 | `openspec-verify-change` | Verify implementation matches specs and design | Artifacts + code | Verification report |
-| 8 | `changelog-generator` | Document change in history | Implemented feature | `changelogs/by-ai/[YYYY-MM-DD]-[feature].md` |
-| 9 | `openspec-archive-change` | Archive completed change | Change ready | `openspec/changes/archive/YYYY-MM-DD-<name>/` |
-| 10 | `openspec-sync-specs` (optional) | Synchronize delta specs to main specs | Delta specs | Main specs updated |
+Before claiming a skill is "done", verify:
+- [ ] I have read the entire SKILL.md file
+- [ ] I have executed ALL steps in the skill
+- [ ] I have the required output artifacts
+- [ ] I can answer: "What did this skill produce?"
+
+**Remember**: Skills are documentation-based workflows with ZERO SKIP policy. Load them by reading the SKILL.md files, execute CLI commands when instructed, and NEVER proceed without completing all steps.
 
 ---
 
-## ✅ Validation Checklist
+## ⚠️ VIOLATION CONSEQUENCES
 
-Before considering any task as **completed**, verify:
+If you SKIP a skill or phase:
+1. The framework integrity is compromised
+2. Quality cannot be guaranteed
+3. You MUST go back and complete what was skipped
+4. No exceptions. No shortcuts. Follow the workflow.
 
-```
-╔═══════════════════════════════════════════════════════════════════════════════════╗
-║                              MANDATORY CHECKLIST                                   ║
-╠═══════════════════════════════════════════════════════════════════════════════════╣
-║                                                                                    ║
-║  □ Security                                                                        ║
-║    └─ □ secure-coding-cybersecurity executed                                     ║
-║    └─ □ No known vulnerabilities (SQL injection, XSS, etc.)                       ║
-║    └─ □ Inputs validated and sanitized                                            ║
-║    └─ □ Secrets/keys not hardcoded                                                ║
-║    └─ □ No eval() or dynamic code execution with user input                       ║
-║                                                                                    ║
-║  □ Maintainability                                                                 ║
-║    └─ □ code-maintainability executed                                            ║
-║    └─ □ Code follows project conventions                                          ║
-║    └─ □ Functions/classes have single responsibility                              ║
-║    └─ □ Descriptive and semantic names                                            ║
-║    └─ □ No duplicate code (DRY principle)                                         ║
-║    └─ □ Documentation explains "why", not "what"                                  ║
-║                                                                                    ║
-║  □ Error Handling                                                                  ║
-║    └─ □ error-handling-patterns applied                                           ║
-║    └─ □ All errors handled gracefully                                             ║
-║    └─ □ Edge cases covered (null, empty, boundaries)                              ║
-║                                                                                    ║
-║  □ Specification (OpenSpec)                                                        ║
-║    └─ □ Change created with proposal, specs, design, tasks                        ║
-║    └─ □ Implementation matches specification                                      ║
-║    └─ □ All WHEN/THEN scenarios implemented                                       ║
-║    └─ □ Design decisions documented                                               ║
-║                                                                                    ║
-║  □ Implementation                                                                  ║
-║    └─ □ All tasks marked complete [- [x]]                                         ║
-║    └─ □ Code tested and functional                                                ║
-║    └─ □ No console.logs or debug code                                             ║
-║                                                                                    ║
-║  □ Validation                                                                      ║
-║    └─ □ systematic-debugging executed without critical errors                     ║
-║    └─ □ openspec-verify-change passed (or reviewed)                               ║
-║    └─ □ Design patterns correctly applied                                         ║
-║                                                                                    ║
-║  □ Documentation                                                                   ║
-║    └─ □ Project index updated if structure changed                                ║
-║    └─ □ Changelog generated in changelogs/by-ai/                                  ║
-║    └─ □ README updated if necessary                                               ║
-║                                                                                    ║
-║  □ Closure                                                                         ║
-║    └─ □ Change archived with openspec-archive-change                              ║
-║    └─ □ Delta specs synchronized (if applicable)                                  ║
-║                                                                                    ║
-╚═══════════════════════════════════════════════════════════════════════════════════╝
+**Quality over speed. Documentation before code. Planning before execution.**