heraspec 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +109 -71
  2. package/bin/heraspec.js +1866 -89
  3. package/bin/heraspec.js.map +4 -4
  4. package/dist/cli/index.d.ts +2 -0
  5. package/dist/commands/audit.d.ts +37 -0
  6. package/dist/commands/create.d.ts +12 -0
  7. package/dist/commands/explore.d.ts +17 -0
  8. package/dist/commands/helper.d.ts +13 -0
  9. package/dist/commands/hotfix.d.ts +9 -0
  10. package/dist/commands/make-code.d.ts +14 -0
  11. package/dist/commands/make-docs.d.ts +36 -0
  12. package/dist/commands/make-test.d.ts +60 -0
  13. package/dist/commands/memory.d.ts +101 -0
  14. package/dist/commands/pack.d.ts +17 -0
  15. package/dist/commands/show.d.ts +8 -0
  16. package/dist/commands/skill.d.ts +8 -0
  17. package/dist/commands/suggest.d.ts +32 -0
  18. package/dist/commands/validate.d.ts +8 -0
  19. package/dist/core/archive.d.ts +14 -0
  20. package/dist/core/config.d.ts +33 -0
  21. package/dist/core/init.d.ts +101 -0
  22. package/dist/core/list.d.ts +7 -0
  23. package/dist/core/memory/config-advisor.d.ts +30 -0
  24. package/dist/core/memory/context-config.d.ts +14 -0
  25. package/dist/core/memory/context-generator.d.ts +19 -0
  26. package/dist/core/memory/index.d.ts +12 -0
  27. package/dist/core/memory/memory-schema.d.ts +34 -0
  28. package/dist/core/memory/memory-search.d.ts +45 -0
  29. package/dist/core/memory/memory-store.d.ts +71 -0
  30. package/dist/core/memory/memory-types.d.ts +159 -0
  31. package/dist/core/memory/memory-vector.d.ts +23 -0
  32. package/dist/core/parsers/code-parser.d.ts +53 -0
  33. package/dist/core/parsers/markdown-parser.d.ts +18 -0
  34. package/dist/core/restore.d.ts +9 -0
  35. package/dist/core/schemas/base.schema.d.ts +58 -0
  36. package/dist/core/schemas/change.schema.d.ts +35 -0
  37. package/dist/core/schemas/index.d.ts +7 -0
  38. package/dist/core/schemas/spec.schema.d.ts +52 -0
  39. package/dist/core/skills/index.d.ts +6 -0
  40. package/dist/core/skills/skill-manager.d.ts +28 -0
  41. package/dist/core/skills/skill-parser.d.ts +24 -0
  42. package/dist/core/sync.d.ts +6 -0
  43. package/dist/core/templates/index.d.ts +10 -0
  44. package/dist/core/templates/skills/README.md +4 -1
  45. package/dist/core/templates/skills/content-channel/content-compliance/skill.md +83 -0
  46. package/dist/core/templates/skills/content-channel/content-prompts/skill.md +74 -0
  47. package/dist/core/templates/skills/content-channel/content-scaffolding/skill.md +82 -0
  48. package/dist/core/templates/skills/content-channel/content-scripting/skill.md +147 -0
  49. package/dist/core/templates/skills/content-channel/content-strategy/skill.md +78 -0
  50. package/dist/core/templates/skills/content-channel/content-vault-sync/skill.md +74 -0
  51. package/dist/core/templates/skills/content-channel/content-voice-adapter/skill.md +143 -0
  52. package/dist/core/templates/skills/content-channel/skill.md +127 -0
  53. package/dist/core/templates/skills/perfex-module/code-quality-guidelines/skill.md +130 -0
  54. package/dist/core/templates/skills/perfex-module/envato-review-guidelines/skill.md +132 -0
  55. package/dist/core/templates/skills/perfex-module/module-codebase/scripts/scaffold-module.js +151 -0
  56. package/dist/core/templates/skills/perfex-module/module-codebase/skill.md +204 -110
  57. package/dist/core/templates/skills/perfex-module/module-codebase/templates/Test_Module.php +79 -0
  58. package/dist/core/templates/skills/perfex-module/module-codebase/templates/controller-admin.php +71 -0
  59. package/dist/core/templates/skills/perfex-module/module-codebase/templates/controller-api.php +58 -0
  60. package/dist/core/templates/skills/perfex-module/module-codebase/templates/deploy.ps1 +97 -0
  61. package/dist/core/templates/skills/perfex-module/module-codebase/templates/helper.php +97 -0
  62. package/dist/core/templates/skills/perfex-module/module-codebase/templates/install.php +30 -0
  63. package/dist/core/templates/skills/perfex-module/module-codebase/templates/model-main.php +94 -0
  64. package/dist/core/templates/skills/perfex-module/module-codebase/templates/module-main.php +91 -0
  65. package/dist/core/templates/skills/perfex-module/module-codebase/templates/package.json +30 -0
  66. package/dist/core/templates/skills/perfex-module/module-codebase/templates/uninstall.php +11 -0
  67. package/dist/core/templates/skills/perfex-module/module-codebase/templates/webpack.config.js +163 -0
  68. package/dist/core/templates/skills/perfex-module/skill.md +50 -0
  69. package/dist/core/templates/skills-template-map.d.ts +29 -0
  70. package/dist/core/validation/validator.d.ts +26 -0
  71. package/dist/core/view.d.ts +4 -0
  72. package/dist/index.d.ts +11 -0
  73. package/dist/index.js +383 -50
  74. package/dist/utils/file-system.d.ts +19 -0
  75. package/dist/utils/index.d.ts +6 -0
  76. package/dist/utils/task-parser.d.ts +26 -0
  77. package/package.json +2 -2
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: content-voice-adapter
3
+ description: Transmute and adapt any arbitrary raw content, article, or idea to match the specific DNA, philosophy, tone of voice, and TTS acoustic standards of any designated channel.
4
+ projectType: content-channel
5
+ ---
6
+
7
+ # Skill: Content Voice Adapter
8
+
9
+ ## Purpose
10
+ Take any arbitrary raw content (raw article, folk story, health tip, social post, quote, reflection, or rough draft) and transmute it through a target channel's **Specific Philosophical Lens & Tone of Voice**, eliminating genre-specific off-brand elements, reframing the core insight, and restructuring it into MTxStudio's standardized 6-part video script schema.
11
+
12
+ ---
13
+
14
+ ## The Dynamic Transmutation Framework
15
+
16
+ Content transmutation is **NOT one-size-fits-all**. What constitutes "off-brand" (lệch tone) and how content is restructured completely change depending on the channel's niche, target audience, and legal constraints.
17
+
18
+ ```text
19
+ ┌────────────────────────────────────────────────────────────────────────┐
20
+ │ 1. CONTENT EXTRACTION & DYNAMIC DE-BIASING │
21
+ │ - Extract core human insight, story premise, or practical value │
22
+ │ - Purge genre-specific negative triggers via De-biasing Matrix │
23
+ │ (e.g., horror: purge real place names & gore; healing: purge │
24
+ │ fatalism & victimhood; health: purge pseudoscience/overpromising)│
25
+ └───────────────────────────────────┬────────────────────────────────────┘
26
+ │
27
+ ┌───────────────────────────────────▼────────────────────────────────────┐
28
+ │ 2. CHANNEL DNA REFRAMING & VOICE PERSONA │
29
+ │ - Reframe core insight through channel philosophy & narrative lens │
30
+ │ - Adapt persona pronouns (I - You / We / 3rd-person narrator) │
31
+ │ - Map vocabulary domain & signature metaphors to audience archetype │
32
+ └───────────────────────────────────┬────────────────────────────────────┘
33
+ │
34
+ ┌───────────────────────────────────▼────────────────────────────────────┐
35
+ │ 3. GENRE-AWARE TTS ACOUSTIC ADAPTATION │
36
+ │ - Enforce sentence pacing: 12-20 words/sentence, 8-12 words/clause │
37
+ │ - Pacing style: Chilling suspense (horror) vs. Gentle warmth │
38
+ │ (healing) vs. Clear instructional (health) vs. Rhythm/rhyme (poem)│
39
+ │ - Prevent Reduplicative Looping, zero artificial tags │
40
+ │ - Preserve \n newline for rhythmic verse and breathing pauses │
41
+ └───────────────────────────────────┬────────────────────────────────────┘
42
+ │
43
+ ┌───────────────────────────────────▼────────────────────────────────────┐
44
+ │ 4. 6-PART SCHEMA & COMPLIANCE ASSEMBLY │
45
+ │ - Fatal Hook (0:00 - 0:15) tailored to format (16:9 or 9:16) │
46
+ │ - Audio Narration Script & Technical Audio Pacing │
47
+ │ - Scene-by-scene Storyboard with Midjourney/Flux Art Style Prompts │
48
+ │ - Facebook Caption & Engagement Hook │
49
+ │ - Genre-Specific Legal Disclaimer (Decree 15 / Medical / Financial) │
50
+ └────────────────────────────────────────────────────────────────────────┘
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Dynamic De-biasing Matrix (Niche-Specific Negative Filtering)
56
+
57
+ When transmuting content, the AI agent MUST consult this matrix to apply the exact negative filtering criteria required for the target niche:
58
+
59
+ | Channel Niche | Reference Channel | Negative Constraints to Purge ("Off-Brand") | Target Transmutation Direction |
60
+ | :--- | :--- | :--- | :--- |
61
+ | **Healing & Psychology** | *Làm Bạn Với Bản Thân*, *An Trú Quán* | ❌ Superstition, fate-blaming, resentment, victim mindset, moral preaching | ✅ Turning inward, acknowledging wounds, emotional boundary setting, inner peace |
62
+ | **Horror & Paranormal** | *Truyện Ma Đêm Mưa* | ❌ Gratuitous gore, real names of temples/pagodas/people (Decree 15 violation), frivolous disrespect, black magic curses | ✅ Safe atmospheric fiction, psychological suspense, eerie mood, karmic retribution, ethical closure |
63
+ | **Health & Wellness** | *Thân An Tâm Lạc* | ❌ Miracle cures, 100% cure guarantees, anti-medical advice, diagnosing diseases, fearmongering | ✅ Everyday safe wellness, gentle stretching, mindful tea/diet, respecting medical guidance |
64
+ | **Life Reflection** | *Góc Chiêm Nghiệm* | ❌ Cynical whining, abstract academic lecturing, impractical theories, hatred or malice | ✅ Pragmatic fortitude, human psychological insight, mindful living, calm composure under adversity |
65
+ | **Philosophy & Zen** | *Tĩnh Tâm Quán* | ❌ Wealth-worship rituals, superstitious fortune telling, sectarian disputes, judging other groups | ✅ Compassionate wisdom, letting go of distress, filial piety to parents, karmic mindfulness |
66
+ | **Poetry & Nostalgia** | *Năm Năm Tháng Tháng* | ❌ Abrupt modern slang, excessive melodrama, bitter resentment toward the past, broken meter | ✅ Lyrical verse / poetic prose, honoring family memories, pure bittersweet nostalgia, musical cadence |
67
+ | **Finance & Business** | *Tài Chính Thực Chiến* | ❌ Guaranteed ROI, get-rich-quick schemes, multi-level marketing, exaggerated product claims | ✅ Prudent money management, investment discipline, objective product evaluation |
68
+
69
+ ---
70
+
71
+ ## Channel DNA Profiles
72
+
73
+ ### 1. Làm Bạn Với Bản Thân (`lam_ban_voi_ban_than`)
74
+ * **Core Philosophy**: "A sanctuary for weary hearts to let go of external expectations and cultivate inner peace."
75
+ * **Persona**: Compassionate, non-judgmental companion.
76
+ * **Transmutation Example**:
77
+ - *Raw*: "You are destined by fate to be alone until your past karmic debt is paid..."
78
+ - ➔ *Transmuted*: "Solitude is a sacred space where you learn to honor your self-worth, set healthy emotional boundaries, and become your own truest friend first."
79
+ * **Audio Voice**: Warm female, slow 112-116 wpm, Lo-fi acoustic solo piano.
80
+ * **Visual Style**: Minimalist pastel watercolor, cozy indoor warmth, gentle natural morning light.
81
+
82
+ ### 2. Truyện Ma Đêm Mưa (`truyen_ma_dem_mua`)
83
+ * **Core Philosophy**: "Telling chilling midnight tales - Karma never misses anyone."
84
+ * **Persona**: Mysterious late-night storyteller with a deep, atmospheric voice and an unwavering moral compass.
85
+ * **Transmutation Example**:
86
+ - *Raw*: Forum story mentioning real pagoda names, graphic torture, and black magic vengeance.
87
+ - ➔ *Transmuted*: Fictionalized story setting (Pagoda T., Village K.), focusing on eerie suspense, psychological fear, and a righteous karmic resolution.
88
+ * **Audio Voice**: Deep male baritone, 118 wpm, Dark Ambient cello, ominous sub-bass.
89
+ * **Visual Style**: Dark cinematic, heavy shadows, flickering candlelight, foggy twilight.
90
+
91
+ ### 3. Tĩnh Tâm Quán (`tinh_tam_quan`)
92
+ * **Core Philosophy**: "A daily verse of mindfulness - Sowing wholesome seeds, letting go of sorrow."
93
+ * **Persona**: Serene spiritual mentor, dignified, deeply compassionate.
94
+ * **Transmutation Example**: Converts daily grievances and rivalry into lessons on releasing grudges, honoring parents, and practicing mindfulness.
95
+ * **Audio Voice**: Mature male, measured 115 wpm, temple bells, bamboo flute.
96
+ * **Visual Style**: Traditional Zen ink wash painting (thủy mặc), misty mountains, white lotus.
97
+
98
+ ### 4. Góc Chiêm Nghiệm (`goc_chiem_nghiem`)
99
+ * **Core Philosophy**: "Pausing amidst the rush - To understand human nature and stride forward with fortitude."
100
+ * **Persona**: Seasoned, poised observer of life, realistic yet never bitter.
101
+ * **Transmutation Example**: Reframes social setbacks into self-reliance, emotional resilience, and calm composure without blaming circumstances.
102
+ * **Audio Voice**: Neutral, poised, 120 wpm, modern acoustic guitar and cello.
103
+ * **Visual Style**: Urban cafe aesthetic, dusk streetlights, warm coffee tones.
104
+
105
+ ### 5. Thân An Tâm Lạc (`than_an_tam_lac`)
106
+ * **Core Philosophy**: "When the body is at ease, the mind finds joy - Small daily habits for a tired body."
107
+ * **Persona**: Attentive wellness practitioner promoting harmony with nature.
108
+ * **Transmutation Example**: Converts exaggerated health hacks into safe relaxation habits (foot baths, acupressure, deep breathing) paired with medical disclaimers.
109
+ * **Audio Voice**: Warm, gentle, relaxed 120 wpm, singing bowls, trickling water sound.
110
+ * **Visual Style**: Organic herbal textures, tea ceremony, morning forest sun.
111
+
112
+ ### 6. Năm Năm Tháng Tháng (`nam_nam_thang_thang`)
113
+ * **Core Philosophy**: "Drifting through months and years, gathering memories into verse."
114
+ * **Persona**: Nostalgic traveler cherishing childhood memories and vintage heirlooms.
115
+ * **Transmutation Example**: Transmutes past hardships and nostalgia into six-eight (*lục bát*) verse or poetic prose honoring parental devotion.
116
+ * **Audio Voice**: Slow rhythmic cadence 110 wpm, acoustic nylon guitar, rain sounds.
117
+ * **Visual Style**: Vintage watercolor, sepia rustic village, retro film photography.
118
+
119
+ ---
120
+
121
+ ## Universal Activation Prompt Template
122
+
123
+ Copy and use this prompt when adapting any raw draft for **any channel**:
124
+
125
+ ```text
126
+ Use skill content-voice-adapter to transmute the raw text below into a production-ready Video Script for channel [CHANNEL_NAME] (Niche: [CHANNEL_NICHE]):
127
+
128
+ [PASTE RAW INPUT TEXT HERE]
129
+
130
+ Execution Requirements across 4 Steps:
131
+ 1. Dynamic De-biasing:
132
+ - Extract core insight and purge all off-brand elements based on the De-biasing Matrix: [List negative constraints, e.g., victim mindset / superstitious fatalism / medical overpromising / graphic gore].
133
+ 2. Channel DNA Reframing:
134
+ - Persona Pronouns: [e.g., Tôi - Bạn / Chúng ta / 3rd-person].
135
+ - Target Emotional State: [e.g., Inner Peace / Gripping Suspense / Soothed Relaxation / Fortitude].
136
+ 3. TTS Acoustic Optimization:
137
+ - Sentence length strictly 12-20 words, comma clauses 8-12 words, zero duplicate reduplicative words.
138
+ - ZERO artificial bracket tags ([breath], [sigh], etc.).
139
+ - Preserve \n newline for poetry or rhythmic breathing.
140
+ 4. MTxStudio 6-Part Schema Packaging:
141
+ - Generate: Fatal Hook, Spoken Narration Script, Visual Storyboard Prompts (English, matching channel art style), Facebook Caption, and Genre-Specific Legal Disclaimer.
142
+ - Spoken script and captions in Vietnamese; Visual Prompts in English.
143
+ ```
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: content-channel
3
+ description: Enterprise guidelines and skill suite for multi-channel social video/audio content production, channel DNA development, AI voice synthesis optimization, and MTxStudio vault integration.
4
+ projectType: content-channel
5
+ ---
6
+
7
+ # Content & Multi-Channel Production Framework
8
+
9
+ This skill suite serves as the authoritative framework for developing, scaling, and managing multi-channel content operations across Facebook, YouTube, TikTok, and Podcasts, integrated directly with the desktop studio application **MTxStudio (Script & Content Vault v2)**.
10
+
11
+ ---
12
+
13
+ ## 1. Core Content Skills Ecosystem
14
+
15
+ ```text
16
+ heraspec/skills/
17
+ ├── content-strategy # Channel positioning, 5-pillar matrix, 14-day Cold Start, $100 RPM monetization
18
+ ├── content-scaffolding # Standard 2-level directory tree, zero [Channel] prefix, export auto-discovery
19
+ ├── content-scripting # Standard 6-part episode authoring, natural acoustic TTS optimization
20
+ ├── content-voice-adapter # Raw content de-biasing and transmutation through target channel DNA
21
+ ├── content-prompts # Cinematic AI visual prompts (Avatar, Cover, Storyboard) & Suno BGM
22
+ ├── content-compliance # Legal safety, platform policy compliance, 3-position disclaimers
23
+ └── content-vault-sync # Data integrity validation, dash sanitization, MTxStudio JSON export
24
+ ```
25
+
26
+ ---
27
+
28
+ ## 2. Inviolable Operational Rules
29
+
30
+ 1. **Golden Naming Rule (Pure Brand Identity)**:
31
+ - ❌ **NEVER** prepend `[Channel]`, `[Kênh]`, or `Channel:` to folder names, identifiers, or titles.
32
+ - ✅ Use 100% pure brand names (e.g., `Làm Bạn Với Bản Thân`, `Truyện Ma Đêm Mưa`, `Thân An Tâm Lạc`, `An Trú Quán`).
33
+
34
+ 2. **2-Level MTxStudio Tree Hierarchy**:
35
+ - Every channel repository maps into standardized subcategories:
36
+ - `_plan` (`type: "docs"`, icon: `Layers`)
37
+ - `_posts` (`type: "article"`, icon: `BookOpen`)
38
+ - `_prompts` (`type: "prompts"`, icon: `Sparkles`)
39
+ - `_music` (`type: "music"`, icon: `Radio`)
40
+ - `_affiliate` (`type: "docs"`, icon: `Tag`, optional)
41
+
42
+ 3. **Natural Acoustic TTS Rules (Clean Voice Synthesis)**:
43
+ - Maintain sentence length between **12 to 20 words** (maximum 25 words).
44
+ - Clauses separated by commas must span **8 to 12 words**.
45
+ - ❌ **ABSOLUTELY NO artificial bracket tags** (e.g., `[breath]`, `[sigh]`, `[0.3s]`, `[lấy hơi]`, `[thở dài]`). Rely entirely on natural punctuation and sentence cadence.
46
+ - Prevent repetition loops on phonetic/reduplicative words by inserting commas and avoiding consecutive duplicate roots.
47
+
48
+ 4. **Poetry & Verse Line Integrity**:
49
+ - Every verse line MUST occupy its own individual line (`\n`). Stanzas must be separated by an empty line (`\n\n`).
50
+ - ❌ NEVER collapse verse lines using `join(' ')`.
51
+
52
+ 5. **3-Position Legal Disclaimer**:
53
+ - For sensitive categories (Horror/Supernatural, Health/Wellness, Psychology, Finance), disclaimers must be deployed in 3 spots:
54
+ 1. Video **Intro Warning Card (0:00 - 0:04)**.
55
+ 2. Post **Caption footer or Pinned Top Comment**.
56
+ 3. Spoken **Audio Narration** for long-form podcasts (>10 mins).
57
+
58
+ ---
59
+
60
+ ## 3. Quick Reference Matrix
61
+
62
+ | Goal | Target Skill | Required Input | Output Artifact |
63
+ | :--- | :--- | :--- | :--- |
64
+ | Plan and position a new channel | `content-strategy` | Channel concept, niche, target audience | 30-day `plan.md`, 5-pillar matrix, RPM KPI |
65
+ | Scaffold folders and initial files | `content-scaffolding` | Channel name, color, icon, slogan | Standard folders, starter post, prompts suite |
66
+ | Write a brand new episode script | `content-scripting` | Channel name, episode topic, pillar | Standard 6-part `posts/{index}.md` script |
67
+ | Transmute raw text into channel DNA | `content-voice-adapter` | Raw draft/article + Target channel | De-biased script aligned with channel voice |
68
+ | Generate visual prompts or Suno BGM | `content-prompts` | Channel name, script scene descriptions | Midjourney/SD prompts, Suno instrumental tags |
69
+ | Audit legal risk and generate disclaimers | `content-compliance` | Channel niche (Horror, Health, Healing) | Standardized legal disclaimer + Warning Card |
70
+ | Package and export to MTxStudio | `content-vault-sync` | Markdown posts, plans, and prompts | Clean `mtxstudio_vault_import.json` bundle |
71
+
72
+ ---
73
+
74
+ ## 4. Multi-Language Directives
75
+
76
+ - **Instruction & Meta-Logic**: All skills and operational reasoning are structured in English for maximum LLM instruction-following accuracy.
77
+ - **Audience-Facing Creative Content**: Generated in the channel's target language as defined in `plan.md` (e.g., Vietnamese, English, Japanese).
78
+ - **Visual & Audio Generation Prompts**: Always formulated in English for optimal image/music synthesis quality (Midjourney, Flux, Stable Diffusion, Suno AI).
79
+ - **Markdown Structural Contract**: When outputting posts for channels processed by `export_vault_json.py`, retain the required section heading literals:
80
+ ```markdown
81
+ # TẬP {number}: {TITLE}
82
+ ## 1. HOOK MỞ ĐẦU
83
+ ## 2. KỊCH BẢN THUYẾT MINH & LỜI THOẠI CHI TIẾT
84
+ ### PHÂN CẢNH VISUAL STORYBOARD
85
+ ## 4. CAPTION FACEBOOK BÀI ĐĂNG
86
+ ## 5. SẢN PHẨM AFFILIATE GẮN KÈM
87
+ ```
88
+
89
+ ---
90
+
91
+ ## 5. Standard Production Workflows
92
+
93
+ ### Workflow A: Daily Script Adaptation from Raw Input
94
+ ```
95
+ [Raw External Article / Story / Idea]
96
+ │
97
+ ▼ (Activate: content-voice-adapter)
98
+ [De-biased, Reframed 6-Part Script Matching Channel DNA]
99
+ │
100
+ ▼ (Activate: content-compliance)
101
+ [Attach Genre Disclaimer & Intro Warning Card Prompt]
102
+ │
103
+ ▼ (Save to: Facebook/[Channel]/posts/{index}.md)
104
+ │
105
+ ▼ (Activate: content-vault-sync)
106
+ [Run export_vault_json.py ➔ Import bundle into MTxStudio]
107
+ ```
108
+
109
+ ### Workflow B: Complete Channel Launch
110
+ ```
111
+ [New Channel Concept]
112
+ │
113
+ ▼ (Activate: content-strategy)
114
+ [30-Day Master Plan plan.md + 5 Pillars + $100 RPM Model]
115
+ │
116
+ ▼ (Activate: content-scaffolding)
117
+ [Create 2-Level Folder Tree + Pure Brand Name + Prompts Suite]
118
+ │
119
+ ▼ (Activate: content-prompts)
120
+ [Generate Avatar 1:1, Cover 16:9, Warning Card & Suno BGM]
121
+ │
122
+ ▼ (Activate: content-scripting)
123
+ [Produce Episode Batches in posts/]
124
+ │
125
+ ▼ (Activate: content-vault-sync)
126
+ [Export Master Vault Package ➔ 1-Click MTxStudio Import]
127
+ ```
@@ -0,0 +1,130 @@
1
+ # Skill: Code Quality, Security & Static Analysis (Perfex Module)
2
+
3
+ ## Purpose
4
+
5
+ This skill defines the software engineering standards, security best practices (OWASP/CWE), static analysis compliance, and Clean Code principles required to build robust, maintainable, and enterprise-grade Perfex CRM modules.
6
+
7
+ Whether submitting to commercial marketplaces (such as Envato / CodeCanyon), deploying to high-load private enterprise environments, or publishing open-source add-ons, following these rules ensures zero security vulnerabilities, optimal concurrency, and smooth automated static analysis scans.
8
+
9
+ ## When to Use
10
+
11
+ - When developing, refactoring, or code-reviewing any Perfex CRM module.
12
+ - When performing security audits and static code analysis (SonarQube, AST scanners, bot linters).
13
+ - When preparing production release archives (`deploy.ps1` or build pipelines).
14
+ - When resolving performance bottlenecks, race conditions, or PHP session locking issues.
15
+
16
+ ---
17
+
18
+ ## Core Software Engineering & Quality Standards
19
+
20
+ ### 1. Separation of Concerns (Zero Inline JS & CSS)
21
+ - **Architectural Rule**: Strict decoupling between Presentation (HTML views), Behavior (JavaScript logic), and Styling (CSS).
22
+ - **Prohibited Patterns**:
23
+ - Inline `<script>` tags inside PHP view templates containing business logic, DOM manipulation, event listeners, or AJAX calls.
24
+ - Inline `<style>` blocks or `style="..."` attributes on HTML tags (both in module views and documentation guides).
25
+ - Hardcoded CSS string arrays declared inside JavaScript files. All styles belong in dedicated `.css` stylesheets.
26
+ - **Standard Practice**:
27
+ - All JavaScript must reside in standalone `.js` files in `assets/js/` (and compiled/minified to `dist/assets/js/`).
28
+ - All CSS must reside in standalone `.css` files in `assets/css/` (and compiled/minified to `dist/assets/css/`).
29
+ - Scripts and stylesheets must be enqueued via Perfex CRM hooks (`app_admin_head`, `app_admin_footer`, `app_customers_head`, `app_customers_footer`).
30
+ - Pass server-side configurations to frontend via centralized localization objects hooked to `app_admin_head` (e.g. `window.{MODULE_UPPERCASE}_CONFIG = ...; window.{MODULE_UPPERCASE}_LANG = ...;`) or semantic HTML5 data attributes (`data-*` / `data-config='...'`) on the root container.
31
+
32
+ ### 2. Static Analysis & AST Scanner Neutrality
33
+ Security scanners and static analysis bots (SonarQube, AST parsers, marketplace review bots) inspect source code for suspicious signatures. Ambiguous or high-risk terminology can trigger false-positive security warnings:
34
+ - **High-Risk Tokens to Avoid**:
35
+ - `inject`, `injection`, `injectStyles`: Often flagged as Script / SQL Injection patterns.
36
+ - `seeder`: Often flagged by automated bots looking for unauthorized database tampering backdoors.
37
+ - `bypass`, `backdoor`, `eval`, `unserialize`: Direct security red flags across all static analysis tools.
38
+ - **Recommended Professional Terminology**:
39
+ - Use `extend` (e.g. `extendTinyMCEStyles`) or `apply` instead of `inject`.
40
+ - Use `demo_data` or `sample_generator` instead of `seeder`.
41
+ - Use `allow` or `permit` instead of `bypass`.
42
+
43
+ ### 3. Safe Dynamic Stylesheet Loading (TinyMCE & Iframes)
44
+ When styling rich text editors or dynamically injected iframes:
45
+ - **NEVER** insert dynamic `<style>` textContent strings containing hardcoded raw CSS.
46
+ - **Native Editor API**:
47
+ ```javascript
48
+ if (editor.dom && typeof editor.dom.loadCSS === 'function') {
49
+ editor.dom.loadCSS(siteUrl + 'modules/{module}/dist/assets/css/{module}_editor.min.css');
50
+ }
51
+ ```
52
+ - **Fallback via Link Element Cloning**:
53
+ ```javascript
54
+ var parentLink = document.querySelector('link[href*="{module}_editor"]');
55
+ if (parentLink && doc.head && !doc.getElementById('{module}-tinymce-styles')) {
56
+ var linkEl = doc.createElement('link');
57
+ linkEl.id = '{module}-tinymce-styles';
58
+ linkEl.rel = 'stylesheet';
59
+ linkEl.href = parentLink.href;
60
+ doc.head.appendChild(linkEl);
61
+ }
62
+ ```
63
+
64
+ ### 4. JavaScript Scope Isolation & Conflict Prevention
65
+ Prevent race conditions, jQuery namespace clashes, and global scope pollution:
66
+ - Enclose 100% of admin scripts in a window load listener and strict IIFE:
67
+ ```javascript
68
+ window.addEventListener('load', function () {
69
+ (function ($) {
70
+ 'use strict';
71
+ // Scoped module logic here
72
+ })(typeof jQuery !== 'undefined' ? jQuery : window.$);
73
+ });
74
+ ```
75
+ - Keep the global `window` scope pristine. Only expose strictly necessary public APIs under a unified module namespace.
76
+
77
+ ### 5. High-Concurrency & PHP Session Lock Prevention
78
+ - In PHP and CodeIgniter, active sessions hold exclusive file locks. Autocomplete lookups, live searches, and read-only AJAX endpoints can cause thread blocking and interface lag when multiple requests queue up.
79
+ - Always release the session lock at the start of read/search controller actions:
80
+ ```php
81
+ // Release PHP session file lock immediately for non-blocking concurrent queries
82
+ session_write_close();
83
+ ```
84
+
85
+ ### 6. Clean Release Packaging & Artifact Isolation
86
+ - Separate development dependencies and test tooling from production runtime artifacts.
87
+ - **Strictly Exclude from Production Distribution**:
88
+ - Development build files: `package.json`, `package-lock.json`, `webpack.config.js`.
89
+ - Testing & scratch code: `tests/`, `test/`, `scratch/`, `*_debug.php`, benchmark scripts.
90
+ - Raw uncompiled assets if using bundled/minified `dist/`.
91
+ - Version control and IDE artifacts: `.git`, `.ai`, `.agents`, `heraspec`, internal project notes.
92
+ - Use packaging scripts (`deploy.ps1` or build scripts) with strict exclusion filters (`/XD`, `/XF`).
93
+
94
+ ### 7. Defensive PHP Security & Database Best Practices
95
+ - **Direct Access Guard**: 100% of PHP files must begin with:
96
+ ```php
97
+ <?php
98
+ defined('BASEPATH') or exit('No direct script access allowed');
99
+ ```
100
+ - **Standard PHP Tags**: Never use short open tags `<?=` or `<?`. Always use standard `<?php echo ...; ?>`.
101
+ - **SQL Injection Prevention (OWASP)**: Never concatenate user input directly into SQL queries. Always use CodeIgniter Query Builder with automatic parameter escaping or `$this->db->escape_str()`.
102
+ - **CSRF Protection**: All POST forms and AJAX requests modifying state must include CSRF tokens:
103
+ ```php
104
+ <input type="hidden" name="<?php echo $this->security->get_csrf_token_name(); ?>" value="<?php echo $this->security->get_csrf_hash(); ?>">
105
+ ```
106
+ And in AJAX:
107
+ ```javascript
108
+ $.ajaxSetup({ data: { [csrf_token_name]: csrf_hash } });
109
+ ```
110
+
111
+ ### 8. DOM XSS Prevention (CWE-79)
112
+ - Never assign raw, unescaped user-controlled strings directly to `.innerHTML`.
113
+ - Use `.textContent`, `.innerText`, `document.createElement()`, or helper functions with strict HTML entity escaping (`escapeHtml()`).
114
+ - Always sanitize rich user-generated content using HTMLPurifier before rendering.
115
+
116
+ ### 9. Enterprise Internationalization (i18n & l10n)
117
+ - **Zero Hardcoded Strings**: 100% of labels, headings, buttons, tooltips, placeholders, and error/feedback messages must use `_l('key')`.
118
+ - Maintain complete parity across supported language catalogs:
119
+ - `language/english/{module}_lang.php`
120
+ - `language/vietnamese/{module}_lang.php` (and other target locales)
121
+ - Never hardcode raw strings like `'Item deleted'` or `'Unauthorized'` in controllers; use centralized language keys.
122
+
123
+ ### 10. Professional Software DNA & Clean Typography
124
+ - 0 emojis in backend PHP, JavaScript, CSS, view templates, comments, or documentation.
125
+ - Maintain a clean, professional, enterprise-grade look and feel consistent with core CRM aesthetics.
126
+
127
+ ---
128
+
129
+ ## Reference Implementation
130
+ - `modules/crosstag/`: Production reference adhering to dual-engine search, `extendTinyMCEStyles()`, Webpack dist bundling, session lock release, and 100% passing automated test assertions.
@@ -0,0 +1,132 @@
1
+ # Skill: Code Quality, Security & Static Analysis (Perfex Module)
2
+
3
+ > **Note**: This skill incorporates the comprehensive static analysis, security, and clean architecture standards required for enterprise deployments, open-source releases, and commercial marketplace submissions (such as Envato / CodeCanyon).
4
+
5
+ ## Purpose
6
+
7
+ This skill defines the software engineering standards, security best practices (OWASP/CWE), static analysis compliance, and Clean Code principles required to build robust, maintainable, and enterprise-grade Perfex CRM modules.
8
+
9
+ Following these rules ensures zero security vulnerabilities, optimal concurrency, and smooth automated static analysis scans (SonarQube, AST linters, automated marketplace review bots).
10
+
11
+ ## When to Use
12
+
13
+ - When developing, refactoring, or code-reviewing any Perfex CRM module.
14
+ - When performing security audits and static code analysis (SonarQube, AST scanners, bot linters).
15
+ - When preparing production release archives (`deploy.ps1` or build pipelines).
16
+ - When resolving performance bottlenecks, race conditions, or PHP session locking issues.
17
+
18
+ ---
19
+
20
+ ## Core Software Engineering & Quality Standards
21
+
22
+ ### 1. Separation of Concerns (Zero Inline JS & CSS)
23
+ - **Architectural Rule**: Strict decoupling between Presentation (HTML views), Behavior (JavaScript logic), and Styling (CSS).
24
+ - **Prohibited Patterns**:
25
+ - Inline `<script>` tags inside PHP view templates containing business logic, DOM manipulation, event listeners, or AJAX calls.
26
+ - Inline `<style>` blocks or `style="..."` attributes on HTML tags (both in module views and documentation guides).
27
+ - Hardcoded CSS string arrays declared inside JavaScript files. All styles belong in dedicated `.css` stylesheets.
28
+ - **Standard Practice**:
29
+ - All JavaScript must reside in standalone `.js` files in `assets/js/` (and compiled/minified to `dist/assets/js/`).
30
+ - All CSS must reside in standalone `.css` files in `assets/css/` (and compiled/minified to `dist/assets/css/`).
31
+ - Scripts and stylesheets must be enqueued via Perfex CRM hooks (`app_admin_head`, `app_admin_footer`, `app_customers_head`, `app_customers_footer`).
32
+ - Pass server-side configurations to frontend via centralized localization objects hooked to `app_admin_head` (e.g. `window.{MODULE_UPPERCASE}_CONFIG = ...; window.{MODULE_UPPERCASE}_LANG = ...;`) or semantic HTML5 data attributes (`data-*` / `data-config='...'`) on the root container.
33
+
34
+ ### 2. Static Analysis & AST Scanner Neutrality
35
+ Security scanners and static analysis bots (SonarQube, AST parsers, marketplace review bots) inspect source code for suspicious signatures. Ambiguous or high-risk terminology can trigger false-positive security warnings:
36
+ - **High-Risk Tokens to Avoid**:
37
+ - `inject`, `injection`, `injectStyles`: Often flagged as Script / SQL Injection patterns.
38
+ - `seeder`: Often flagged by automated bots looking for unauthorized database tampering backdoors.
39
+ - `bypass`, `backdoor`, `eval`, `unserialize`: Direct security red flags across all static analysis tools.
40
+ - **Recommended Professional Terminology**:
41
+ - Use `extend` (e.g. `extendTinyMCEStyles`) or `apply` instead of `inject`.
42
+ - Use `demo_data` or `sample_generator` instead of `seeder`.
43
+ - Use `allow` or `permit` instead of `bypass`.
44
+
45
+ ### 3. Safe Dynamic Stylesheet Loading (TinyMCE & Iframes)
46
+ When styling rich text editors or dynamically injected iframes:
47
+ - **NEVER** insert dynamic `<style>` textContent strings containing hardcoded raw CSS.
48
+ - **Native Editor API**:
49
+ ```javascript
50
+ if (editor.dom && typeof editor.dom.loadCSS === 'function') {
51
+ editor.dom.loadCSS(siteUrl + 'modules/{module}/dist/assets/css/{module}_editor.min.css');
52
+ }
53
+ ```
54
+ - **Fallback via Link Element Cloning**:
55
+ ```javascript
56
+ var parentLink = document.querySelector('link[href*="{module}_editor"]');
57
+ if (parentLink && doc.head && !doc.getElementById('{module}-tinymce-styles')) {
58
+ var linkEl = doc.createElement('link');
59
+ linkEl.id = '{module}-tinymce-styles';
60
+ linkEl.rel = 'stylesheet';
61
+ linkEl.href = parentLink.href;
62
+ doc.head.appendChild(linkEl);
63
+ }
64
+ ```
65
+
66
+ ### 4. JavaScript Scope Isolation & Conflict Prevention
67
+ Prevent race conditions, jQuery namespace clashes, and global scope pollution:
68
+ - Enclose 100% of admin scripts in a window load listener and strict IIFE:
69
+ ```javascript
70
+ window.addEventListener('load', function () {
71
+ (function ($) {
72
+ 'use strict';
73
+ // Scoped module logic here
74
+ })(typeof jQuery !== 'undefined' ? jQuery : window.$);
75
+ });
76
+ ```
77
+ - Keep the global `window` scope pristine. Only expose strictly necessary public APIs under a unified module namespace.
78
+
79
+ ### 5. High-Concurrency & PHP Session Lock Prevention
80
+ - In PHP and CodeIgniter, active sessions hold exclusive file locks. Autocomplete lookups, live searches, and read-only AJAX endpoints can cause thread blocking and interface lag when multiple requests queue up.
81
+ - Always release the session lock at the start of read/search controller actions:
82
+ ```php
83
+ // Release PHP session file lock immediately for non-blocking concurrent queries
84
+ session_write_close();
85
+ ```
86
+
87
+ ### 6. Clean Release Packaging & Artifact Isolation
88
+ - Separate development dependencies and test tooling from production runtime artifacts.
89
+ - **Strictly Exclude from Production Distribution**:
90
+ - Development build files: `package.json`, `package-lock.json`, `webpack.config.js`.
91
+ - Testing & scratch code: `tests/`, `test/`, `scratch/`, `*_debug.php`, benchmark scripts.
92
+ - Raw uncompiled assets if using bundled/minified `dist/`.
93
+ - Version control and IDE artifacts: `.git`, `.ai`, `.agents`, `heraspec`, internal project notes.
94
+ - Use packaging scripts (`deploy.ps1` or build scripts) with strict exclusion filters (`/XD`, `/XF`).
95
+
96
+ ### 7. Defensive PHP Security & Database Best Practices
97
+ - **Direct Access Guard**: 100% of PHP files must begin with:
98
+ ```php
99
+ <?php
100
+ defined('BASEPATH') or exit('No direct script access allowed');
101
+ ```
102
+ - **Standard PHP Tags**: Never use short open tags `<?=` or `<?`. Always use standard `<?php echo ...; ?>`.
103
+ - **SQL Injection Prevention (OWASP)**: Never concatenate user input directly into SQL queries. Always use CodeIgniter Query Builder with automatic parameter escaping or `$this->db->escape_str()`.
104
+ - **CSRF Protection**: All POST forms and AJAX requests modifying state must include CSRF tokens:
105
+ ```php
106
+ <input type="hidden" name="<?php echo $this->security->get_csrf_token_name(); ?>" value="<?php echo $this->security->get_csrf_hash(); ?>">
107
+ ```
108
+ And in AJAX:
109
+ ```javascript
110
+ $.ajaxSetup({ data: { [csrf_token_name]: csrf_hash } });
111
+ ```
112
+
113
+ ### 8. DOM XSS Prevention (CWE-79)
114
+ - Never assign raw, unescaped user-controlled strings directly to `.innerHTML`.
115
+ - Use `.textContent`, `.innerText`, `document.createElement()`, or helper functions with strict HTML entity escaping (`escapeHtml()`).
116
+ - Always sanitize rich user-generated content using HTMLPurifier before rendering.
117
+
118
+ ### 9. Enterprise Internationalization (i18n & l10n)
119
+ - **Zero Hardcoded Strings**: 100% of labels, headings, buttons, tooltips, placeholders, and error/feedback messages must use `_l('key')`.
120
+ - Maintain complete parity across supported language catalogs:
121
+ - `language/english/{module}_lang.php`
122
+ - `language/vietnamese/{module}_lang.php` (and other target locales)
123
+ - Never hardcode raw strings like `'Item deleted'` or `'Unauthorized'` in controllers; use centralized language keys.
124
+
125
+ ### 10. Professional Software DNA & Clean Typography
126
+ - 0 emojis in backend PHP, JavaScript, CSS, view templates, comments, or documentation.
127
+ - Maintain a clean, professional, enterprise-grade look and feel consistent with core CRM aesthetics.
128
+
129
+ ---
130
+
131
+ ## Reference Implementation
132
+ - `modules/crosstag/`: Production reference adhering to dual-engine search, `extendTinyMCEStyles()`, Webpack dist bundling, session lock release, and 100% passing automated test assertions.