@xingyu.wang/evoskills 2.0.0 → 2.2.0

package/.github/AI_CONSTITUTION.md

@@ -37,6 +37,44 @@ Without evolution, the AI repeats the same mistakes. With evolution, every error
 
 ---
 
+## Core Evolution Infrastructure
+
+The AI evolution mechanism relies on **two core skills** that are always active and non-negotiable:
+
+### 1. **_evolution-core** (Tier 1)
+- **Purpose**: Identifies improvement opportunities in code, processes, and workflows
+- **Responsibility**: Pattern recognition, root cause analysis, and improvement proposal
+- **Activation**: Triggered by errors, user feedback, or complex workflows
+- **Output**: Constitutional updates, new skills, or instruction refinements
+- **Critical**: This is the system's learning mechanism - without it, evolution cannot happen
+
+### 2. **_skills-manager** (Tier 1)
+- **Purpose**: Manages the complete skill lifecycle (init, install, remove, update)
+- **Responsibility**: Skill registry maintenance, dependency tracking, skill contributions
+- **Activation**: Triggered when new skills are created, modified, or removed
+- **Output**: Updated AGENTS.md, skill documentation, registry consistency
+- **Critical**: This is the system's knowledge infrastructure - without it, skills cannot be discovered or maintained
+
+### How They Work Together
+
+**Evolution Loop** in the AI system:
+
+```
+Error/Feedback → _evolution-core detects pattern
+                       ↓
+                Creates/improves skill
+                       ↓
+              _skills-manager registers it
+                       ↓
+         Skill becomes available for AI use
+                       ↓
+            Subsequent sessions benefit
+```
+
+These two skills form the **evolutionary backbone** of the system. All other skills exist to enhance specific workflows, but these two core skills enable the entire evolution mechanism itself.
+
+---
+
 ## Skill Modularity Principle
 
 **Key design decisions:**
@@ -50,6 +88,26 @@ When creating skill `_my-skill`, you only need to declare its tier and dependenc
 
 ---
 
+## Mandatory Initialization Binding
+
+The constitution defines **why** evolution and discipline are required.
+The initialization protocol defines **how** every response is enforced.
+
+### Authority and layering
+
+1. **Constitution** (`.github/AI_CONSTITUTION.md`): immutable evolution principles
+2. **Initialization protocol** (`.github/AI_INITIALIZATION.md`): mandatory 4-phase execution contract
+3. **Instruction entrypoint** (`.github/copilot-instructions.md`): active loading and per-response gate
+4. **Skill definitions** (`.agent/skills/*/SKILL.md`): implementation details
+
+### Compliance contract
+
+- A response is valid only when it satisfies all required initialization markers and checks.
+- If any required phase is missing, execution must stop and resume from the missing phase.
+- Evolution outputs (new rules/skills) must remain compatible with this enforcement chain.
+
+---
+
 ## Glossary
 
 | Term | Definition |
@@ -63,4 +121,4 @@ When creating skill `_my-skill`, you only need to declare its tier and dependenc
 
 > **Version**: 2.1  
 > **Focus**: Evolution mechanism only (lean and focused)  
-> **Related Files**: See `.github/EXECUTION_RULES.md` for mandatory rules, `AGENTS.md` for skill registry
+> **Related Files**: `.github/AI_INITIALIZATION.md`, `.github/copilot-instructions.md`, `AGENTS.md`

package/README.md

@@ -56,7 +56,10 @@ This will:
 **Three-layer architecture:**
 1. **AI Constitution** - Evolution principles (always active, cannot be disabled)
 2. **Execution Rules** - 4 optional safety guardrails (can be removed if not needed)
-3. **Skills** - Reusable capabilities (5 core required, 9 optional)
+3. **Skills** - Reusable capabilities with 3 tiers:
+  - Core (2): always installed
+  - Required System (4): safety/runtime baseline
+  - Optional (8): user-selectable workflow skills
 
 ## 📚 Usage
 
@@ -67,6 +70,15 @@ evoskills list                   # Show all available skills
 evoskills list --installed       # Show installed skills only
 ```
 
+### Initialize by Tier
+
+```bash
+evoskills init                   # Install core + required + optional (default)
+evoskills init --core-only       # Install only core skills (2)
+evoskills init --required-only   # Install core + required system skills (6)
+evoskills init --skills _git-commit,_pr-creator  # Install selected optional skills
+```
+
 ### Install/Remove Skills
 
 ```bash
@@ -81,6 +93,12 @@ evoskills update                 # Update CLI (via npm) and refresh all installe
 evoskills update _git-commit     # Update specific skill only
 ```
 
+### npm Release Authentication (GitHub Actions)
+
+- Preferred: **Trusted Publishing (OIDC)**, no token needed
+- Fallback: **Granular access token** stored as `NPM_TOKEN` in GitHub Secrets
+- Note: npm legacy tokens were removed (Nov 2025), so "Automation token" may not appear in UI
+
 ### Use Custom Skill Repository
 
 ```bash
@@ -92,31 +110,27 @@ The repository URL is auto-saved to `.evoskills-config.json`.
 
 ## 🎯 Available Skills
 
-The default repository provides 14 skills across 5 categories:
+The default repository provides 14 skills in a 3-tier model:
 
-### Core Skills (Required - Auto-installed)
-- `_instruction-guard` - Ensures project instructions are always read before responses
-- `_context-ack` - Formats responses with headers and reference lists
-- `_file-output-guard` - Prevents accidental file overwrites
-- `_execution-precheck` - Validates dependencies before executing commands
+### Tier 1: Core Skills (2)
 - `_evolution-core` - Identifies improvement opportunities and proposes enhancements
+- `_skills-manager` - Manages skill lifecycle (install/remove/update/contribute)
 
-### Git & Version Control
-- `_git-commit` - Conventional commits workflow
-- `_pr-creator` - Automate PR generation
-
-### Release Management
-- `_release-process` - Complete release workflow
+### Tier 2: Required System Skills (4)
+- `_instruction-guard` - Ensures project instructions are applied before responses
+- `_context-ack` - Formats responses with clear context and references
+- `_file-output-guard` - Safeguards file operations and output behavior
+- `_execution-precheck` - Validates dependencies before execution
 
-### Code Quality
-- `_code-health-check` - Quality checks before commit
-- `_typescript-type-safety` - TypeScript type safety guidelines
-
-### Workflow & Automation
-- `_change-summary` - Summarize work sessions
-- `_traceability-check` - Ensure decisions are documented
-- `_session-safety` - Prevent state violations
-- `_skills-manager` - Manage skills lifecycle
+### Tier 3: Optional Skills (8)
+- `_git-commit` - Conventional commits workflow
+- `_pr-creator` - PR generation workflow
+- `_release-process` - End-to-end release process
+- `_code-health-check` - Pre-commit quality checks
+- `_typescript-type-safety` - Type safety and mock patterns
+- `_change-summary` - Session change summarization
+- `_traceability-check` - Decision traceability checks
+- `_session-safety` - Session state consistency safeguards
 
 ## 🛡️ User Content Protection
 

package/evoskills

@@ -3,7 +3,7 @@
 set -e
 
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-CLI_VERSION="2.0.0"
+CLI_VERSION="2.1.0"
 
 # Project config file (in current directory)
 PROJECT_CONFIG_FILE=".evoskills-config.json"
@@ -21,11 +21,15 @@ RED='\033[0;31m'
 NC='\033[0m'
 
 CORE_SKILLS=(
+  "_evolution-core"
+  "_skills-manager"
+)
+
+REQUIRED_SKILLS=(
   "_instruction-guard"
   "_context-ack"
   "_file-output-guard"
   "_execution-precheck"
-  "_evolution-core"
 )
 
 OPTIONAL_SKILLS=(
@@ -37,7 +41,6 @@ OPTIONAL_SKILLS=(
   "_change-summary"
   "_traceability-check"
   "_session-safety"
-  "_skills-manager"
 )
 
 print_success() { echo -e "${GREEN}✅ $*${NC}"; }
@@ -54,7 +57,8 @@ Usage:
 
 Commands:
   init [OPTIONS]              Initialize project skills
-    --core-only               Install core required skills only
+    --core-only               Install core skills only (2 skills)
+    --required-only           Install core + required system skills
     --skills <list>           Install selected skills (comma-separated)
     --all                     Install all skills (default)
     --repo <url>              Use custom skill repository (saved to .evoskills-config.json)
@@ -77,6 +81,7 @@ Notes:
   - Repository URL is auto-saved in .evoskills-config.json when using --repo
   - 'update' without args refreshes CLI (via npm) and all skills from saved repo
   - AGENTS.md is auto-generated for openskills compatibility
+  - Skill tiers: Core (2), Required System (4), Optional (8)
 EOF
 }
 
@@ -180,7 +185,7 @@ For additional safety guardrails, see:
 ## Skills Registry
 
 For available skills and how they work:
-- `AGENTS.md` - Skill registry with `_evolution-core` as the core skill
+- `AGENTS.md` - Skill registry with core, required system, and optional skills
 
 ---
 
@@ -228,8 +233,46 @@ EOF
 }
 
 write_agents_registry() {
-  local installed_list
-  installed_list=$(find "$SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; 2>/dev/null | sort)
+  local is_installed
+  is_installed() {
+    [ -d "$SKILLS_DIR/$1" ]
+  }
+
+  local skill_description
+  skill_description() {
+    case "$1" in
+      _evolution-core) echo "Identify improvement opportunities and patterns in code and processes. Proposes enhancements based on architectural patterns and best practices. Core mechanism of continuous system evolution." ;;
+      _skills-manager) echo "Core skill manager for evoskills. Handles skill lifecycle (init, install, remove, update) and skill contributions. Core mechanism managing the skill ecosystem." ;;
+      _instruction-guard) echo "Read and apply directives before processing each request. Enforces instruction hierarchy and prevents instruction conflicts." ;;
+      _context-ack) echo "Format responses with clear headers, footers, and reference lists. Ensures proper context acknowledgment and response structure." ;;
+      _file-output-guard) echo "Validate and safeguard all file creation operations. Prevents unsafe file creation patterns and unauthorized modifications." ;;
+      _execution-precheck) echo "Validate dependencies and runtime requirements before executing commands. Ensures all prerequisites are met before task execution." ;;
+      _git-commit) echo "Implement conventional commits workflow. Ensures proper commit message formatting and semantic versioning compliance." ;;
+      _pr-creator) echo "Automate PR generation with version detection and release notes. Streamlines contributions and version management." ;;
+      _release-process) echo "Execute complete release workflow. Coordinates versioning, tagging, and publication of releases." ;;
+      _code-health-check) echo "Perform quality checks before commit. Validates code standards, security, and architectural consistency." ;;
+      _typescript-type-safety) echo "Enforce TypeScript type safety guidelines. Ensures proper typing and prevents type-related runtime errors." ;;
+      _change-summary) echo "Summarize completed work sessions. Provides concise summaries of changes and progress made." ;;
+      _traceability-check) echo "Ensure all decisions are properly documented. Validates decision traceability and documentation completeness." ;;
+      _session-safety) echo "Prevent state violations and session inconsistencies. Maintains context integrity and prevents conflicting actions." ;;
+      *) echo "Skill: $1" ;;
+    esac
+  }
+
+  local add_skill_entry
+  add_skill_entry() {
+    local skill="$1"
+    if is_installed "$skill"; then
+      cat >> "$temp_content" << EOF
+<skill>
+<name>$skill</name>
+<description>$(skill_description "$skill")</description>
+<location>project</location>
+</skill>
+
+EOF
+    fi
+  }
 
   # Generate our skills section in a temp file
   local temp_content=".evoskills-section.tmp"
@@ -259,21 +302,33 @@ Usage notes:
 
 <available_skills>
 
+<!-- Tier 1: Core Skills (2) - Evolution Infrastructure -->
+
 MARKER_EOF
 
-  # Add installed skills
-  if [ -n "$installed_list" ]; then
-    while IFS= read -r skill; do
-      cat >> "$temp_content" << EOF
-<skill>
-<name>$skill</name>
-<description>Skill: $skill</description>
-<location>project</location>
-</skill>
+  for skill in "${CORE_SKILLS[@]}"; do
+    add_skill_entry "$skill"
+  done
 
-EOF
-    done <<< "$installed_list"
-  fi
+  cat >> "$temp_content" << 'MARKER_EOF'
+
+<!-- Tier 2: System Skills (4) - Required for Safe Operation -->
+
+MARKER_EOF
+
+  for skill in "${REQUIRED_SKILLS[@]}"; do
+    add_skill_entry "$skill"
+  done
+
+  cat >> "$temp_content" << 'MARKER_EOF'
+
+<!-- Tier 3: Optional Skills (8) - User-Selectable Enhancements -->
+
+MARKER_EOF
+
+  for skill in "${OPTIONAL_SKILLS[@]}"; do
+    add_skill_entry "$skill"
+  done
 
   cat >> "$temp_content" << 'MARKER_EOF'
 
@@ -366,6 +421,7 @@ install_skill_github() {
 
 cmd_init() {
   local core_only=false
+  local required_only=false
   local skills=""
   local install_all=true
   local custom_repo=""
@@ -377,6 +433,11 @@ cmd_init() {
         install_all=false
         shift
         ;;
+      --required-only)
+        required_only=true
+        install_all=false
+        shift
+        ;;
       --skills)
         skills="$2"
         install_all=false
@@ -402,7 +463,7 @@ cmd_init() {
 
   cat > "$PROJECT_CONFIG_FILE" << EOF
 {
-  "version": "1.1.0",
+  "version": "2.1.0",
   "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "skillsDir": ".agent/skills",
   "openskillsCompatible": true,
@@ -420,6 +481,13 @@ EOF
   done
 
   if [ "$core_only" = false ]; then
+    print_info "Installing required system skills..."
+    for skill in "${REQUIRED_SKILLS[@]}"; do
+      install_skill_github "$skill"
+    done
+  fi
+
+  if [ "$core_only" = false ] && [ "$required_only" = false ]; then
     if [ -n "$skills" ]; then
       print_info "Installing selected skills..."
       for skill in ${skills//,/ }; do
@@ -461,6 +529,11 @@ cmd_list() {
     echo "  - $skill"
   done
 
+  echo "Required system skills:"
+  for skill in "${REQUIRED_SKILLS[@]}"; do
+    echo "  - $skill"
+  done
+
   echo "Optional skills:"
   for skill in "${OPTIONAL_SKILLS[@]}"; do
     echo "  - $skill"
@@ -481,8 +554,8 @@ cmd_remove() {
   [ -z "$skill" ] && { print_error "Usage: evoskills remove <skill>"; exit 1; }
 
   case "$skill" in
-    _instruction-guard|_context-ack|_file-output-guard|_execution-precheck|_evolution-core)
-      print_error "Cannot remove core skill: $skill"
+    _evolution-core|_skills-manager|_instruction-guard|_context-ack|_file-output-guard|_execution-precheck)
+      print_error "Cannot remove core/required skill: $skill"
       exit 1
       ;;
   esac

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@xingyu.wang/evoskills",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Evolution Skills CLI for installing and managing openskills-compatible AI skills.",
   "license": "MIT",
   "bin": {
     "evoskills": "./evoskills"
   },
+  "scripts": {
+    "version:patch": "npm version patch -m 'chore(release): bump version to %s'",
+    "version:minor": "npm version minor -m 'chore(release): bump version to %s'",
+    "version:major": "npm version major -m 'chore(release): bump version to %s'",
+    "postversion": "git push origin main --tags"
+  },
   "files": [
     "evoskills",
     "README.md",
@@ -21,6 +27,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/xingyu.wang/copilot-evolution-skills.git"
+    "url": "https://github.com/wxy/copilot-evolution-skills.git"
   }
 }

package/.github/EXECUTION_RULES.md

@@ -1,105 +0,0 @@
-# Execution Rules
-
-> Optional rules that enforce safe and predictable AI behavior. Install with evoskills; can be deleted if not needed for your use case.
-
----
-
-## Overview
-
-These 4 rules form the guardrails for reliable AI execution. They are **auto-enforced by the core system** when enabled, but can be selectively disabled or removed if your workflow doesn't require them.
-
-**Install Status**: These rules are auto-installed by `evoskills init`. To disable, remove this file's entry from `.github/copilot-instructions.md`.
-
----
-
-## Rule 1: Instruction Guard (_instruction-guard)
-
-**Purpose**: Ensure project context is always loaded before responding.
-
-**When Active**: Before each response, if project instruction file (`.github/copilot-instructions.md`) is not in current context, read it immediately.
-
-**Why**: Prevents deviations due to missing project-specific requirements.
-
----
-
-## Rule 2: Context Acknowledgment (_context-ack)
-
-**Purpose**: Enable users to quickly verify the AI is following correct rules.
-
-**When Active**: Each response must follow specified output format:
-- Fixed prefix at start
-- Polite address line
-- Main content
-- Reference list at end (showing which files/rules were consulted)
-
-**Why**: Makes compliance transparent and auditable.
-
----
-
-## Rule 3: File Output Guard (_file-output-guard)
-
-**Purpose**: Prevent accidental file overwrites and unsafe operations.
-
-**When Active**:
-- **Forbidden**: Using HERE documents for file creation (`cat > file << 'EOF'`)
-- **Required**: Use `create_file` or `replace_string_in_file` tools only
-- **Large Files**: Files >5KB must be segmented to same file to avoid session limits
-
-**Why**: Ensures file operations are safe, traceable, and controllable.
-
----
-
-## Rule 4: Session Safety (_session-safety)
-
-**Purpose**: Prevent session failure due to excessive output.
-
-**When Active**: When estimated output length exceeds 5KB:
-- Segment processing or write to file instead
-- Don't output overly long content in single response
-
-**Why**: Protects conversation session from breaking.
-
----
-
-## How These Rules Work Together
-
-```
-Rule 1 (_instruction-guard)
-    ↓ [load context]
-Rule 2 (_context-ack)
-    ↓ [format response]
-Rule 3 (_file-output-guard)
-    ↓ [file operations safe]
-Rule 4 (_session-safety)
-    ↓ [output within limits]
-✅ Safe, predictable, auditable execution
-```
-
----
-
-## When to Disable
-
-You can safely remove this file's reference from `.github/copilot-instructions.md` if:
-
-1. You're using the AI in personal projects with low risk tolerance
-2. Your workflow doesn't need output format enforcement
-3. You want maximum flexibility without guardrails
-
-However, we recommend keeping at least **Rule 1** (_instruction-guard) enabled for project-based work.
-
----
-
-## Relationship to Evolution
-
-These rules are **separate from evolution**. Evolution (in AI_CONSTITUTION.md) happens automatically when triggers fire. These rules ensure safe execution during evolution and regular tasks.
-
-Think of it this way:
-- **Constitution** = "How the AI learns"
-- **Execution Rules** = "How the AI operates safely"
-- **Skills** = "What the AI does"
-
----
-
-> **Version**: 1.0  
-> **Install Source**: evoskills (auto-installed with `evoskills init`)  
-> **Customization**: Can be extended in project-specific instruction files