@xingyu.wang/evoskills 3.0.0 → 3.1.0

package/README.md

@@ -49,17 +49,17 @@ This will:
 - ✅ Create `.agent/skills/` directory (skills installed from GitHub)
 - ✅ Generate `AGENTS.md` at project root (openskills-compatible skill registry)
 - ✅ Download `.github/AI_CONSTITUTION.md` (core evolution mechanism)
-- ✅ Download `.github/EXECUTION_RULES.md` (optional safety guardrails)
+- ✅ Download `.github/AI_INITIALIZATION.md` (mandatory 4-skill initialization protocol)
 - ✅ Create `.github/copilot-instructions.md` (entry point for the system)
 - ✅ Save configuration to `.evoskills-config.json`
 
-**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)
+**Architecture:**
+1. **AI Constitution** - Core evolution principles (always active)
+2. **Initialization Protocol** - Mandatory 4-skill execution sequence with verifiable markers
 3. **Skills** - Reusable capabilities with 3 tiers:
-  - Core (2): always installed
-  - Required System (4): safety/runtime baseline
-  - Optional (8): user-selectable workflow skills
+  - Core (2): evolution infrastructure
+  - Required System (4): safety/runtime baseline (enforced by initialization protocol)
+  - Optional (8): user-selectable workflow enhancements
 
 ## 📚 Usage
 
@@ -144,7 +144,7 @@ evoskills intelligently preserves your customizations during updates:
 
 ### copilot-instructions.md Protection
 - New file: Creates standard template with required references
-- Existing file: Checks for `AI_CONSTITUTION.md` and `AGENTS.md` references
+- Existing file: Checks for `AI_CONSTITUTION.md`, `AI_INITIALIZATION.md`, and `AGENTS.md` references
 - Only appends missing references, never overwrites existing content
 
 **Example**: You can safely add your own skill groups to `AGENTS.md` - evoskills updates won't touch them.

package/evoskills

@@ -3,7 +3,7 @@
 set -e
 
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-CLI_VERSION="3.0.0"
+CLI_VERSION="3.1.0"
 
 # Project config file (in current directory)
 PROJECT_CONFIG_FILE=".evoskills-config.json"
@@ -90,6 +90,15 @@ ensure_layout() {
   mkdir -p ".github"
 }
 
+github_raw_url() {
+  local repo_url="$1"
+  local path="$2"
+  # Convert https://github.com/user/repo to https://raw.githubusercontent.com/user/repo/main/path
+  local raw_repo
+  raw_repo=$(echo "$repo_url" | sed 's|https://github.com/|https://raw.githubusercontent.com/|' | sed 's|\.git$||')
+  echo "$raw_repo/main/$path"
+}
+
 get_config_value() {
   local key="$1"
 
@@ -134,37 +143,91 @@ set_config_value() {
   print_success "Config saved: $key = $value"
 }
 
+# Download file from GitHub with strict error handling
+# Usage: github_download <skills_repo> <file_path> <output_file> <allow_stub>
+# allow_stub: if 'true', fail fast on error; if 'false', skip on error
+github_download() {
+  local skills_repo="$1"
+  local file_path="$2"
+  local output_file="$3"
+  local allow_stub="$4"
+  local raw_url
+  local temp_file
+  
+  raw_url=$(github_raw_url "$skills_repo" "$file_path")
+  temp_file=$(mktemp)
+  
+  if curl -sf "$raw_url" > "$temp_file" 2>/dev/null; then
+    mv "$temp_file" "$output_file"
+    print_success "Downloaded $file_path"
+    return 0
+  else
+    rm -f "$temp_file"
+    if [ "$allow_stub" = "true" ]; then
+      print_error "Failed to download $file_path from $skills_repo"
+      print_error "Cannot initialize project without critical files"
+      return 1
+    else
+      print_warn "Could not download $file_path; skipping update"
+      return 2
+    fi
+  fi
+}
+
 create_constitution_if_missing() {
   if [ ! -f ".github/AI_CONSTITUTION.md" ]; then
     local skills_repo
     skills_repo=$(get_config_value "skillsRepo")
-
-    if curl -sf "$skills_repo/raw/main/.github/AI_CONSTITUTION.md" > ".github/AI_CONSTITUTION.md" 2>/dev/null; then
-      print_success "Downloaded .github/AI_CONSTITUTION.md"
-    else
-      cat > ".github/AI_CONSTITUTION.md" << 'EOF'
-# AI Constitution
-
-Please add your project constitution here or configure the skills repository URL.
-EOF
-      print_warn "Could not download constitution; created minimal .github/AI_CONSTITUTION.md"
+    github_download "$skills_repo" ".github/AI_CONSTITUTION.md" ".github/AI_CONSTITUTION.md" "true"
+    if [ $? -ne 0 ]; then
+      print_error "AI_CONSTITUTION.md is required for initialization"
+      exit 1
     fi
   fi
 }
 
-create_execution_rules_if_missing() {
-  if [ ! -f ".github/EXECUTION_RULES.md" ]; then
+create_initialization_if_missing() {
+  if [ ! -f ".github/AI_INITIALIZATION.md" ]; then
     local skills_repo
     skills_repo=$(get_config_value "skillsRepo")
-
-    if curl -sf "$skills_repo/raw/main/.github/EXECUTION_RULES.md" > ".github/EXECUTION_RULES.md" 2>/dev/null; then
-      print_success "Downloaded .github/EXECUTION_RULES.md"
-    else
-      print_warn "Could not download execution rules (optional)"
+    github_download "$skills_repo" ".github/AI_INITIALIZATION.md" ".github/AI_INITIALIZATION.md" "true"
+    if [ $? -ne 0 ]; then
+      print_error "AI_INITIALIZATION.md is required for initialization"
+      exit 1
     fi
   fi
 }
 
+update_constitution() {
+  local skills_repo
+  skills_repo=$(get_config_value "skillsRepo")
+  local raw_url
+  raw_url=$(github_raw_url "$skills_repo" ".github/AI_CONSTITUTION.md")
+  
+  if curl -sf "$raw_url" > ".github/AI_CONSTITUTION.md" 2>/dev/null; then
+    print_success "Updated .github/AI_CONSTITUTION.md"
+    return 0
+  else
+    print_warn "Could not update .github/AI_CONSTITUTION.md from remote"
+    return 1
+  fi
+}
+
+update_initialization() {
+  local skills_repo
+  skills_repo=$(get_config_value "skillsRepo")
+  local raw_url
+  raw_url=$(github_raw_url "$skills_repo" ".github/AI_INITIALIZATION.md")
+  
+  if curl -sf "$raw_url" > ".github/AI_INITIALIZATION.md" 2>/dev/null; then
+    print_success "Updated .github/AI_INITIALIZATION.md"
+    return 0
+  else
+    print_warn "Could not update .github/AI_INITIALIZATION.md from remote"
+    return 1
+  fi
+}
+
 create_copilot_instructions_if_missing() {
   if [ ! -f ".github/copilot-instructions.md" ]; then
     cat > ".github/copilot-instructions.md" << 'EOF'
@@ -177,10 +240,10 @@ applyTo: "**"
 Please read and follow the AI evolution principle:
 - `.github/AI_CONSTITUTION.md` - Core evolution mechanism (always active, cannot be disabled)
 
-## Optional Execution Rules
+## Mandatory Initialization Protocol
 
-For additional safety guardrails, see:
-- `.github/EXECUTION_RULES.md` - 4 optional rules (can be disabled if not needed for your use case)
+For enforced execution sequence:
+- `.github/AI_INITIALIZATION.md` - 4-skill initialization protocol (mandatory before each response)
 
 ## Skills Registry
 
@@ -193,41 +256,19 @@ For available skills and how they work:
 EOF
     print_success "Created .github/copilot-instructions.md"
   else
-    # Check if file already contains required references
-    local has_constitution=false
-    local has_execution=false
-    local has_agents=false
-    
-    if grep -q "AI_CONSTITUTION.md" ".github/copilot-instructions.md"; then
-      has_constitution=true
-    fi
-    
-    if grep -q "EXECUTION_RULES.md" ".github/copilot-instructions.md"; then
-      has_execution=true
-    fi
-    
-    if grep -q "AGENTS.md" ".github/copilot-instructions.md"; then
-      has_agents=true
-    fi
-    
-    # Append missing references
-    if [ "$has_constitution" = false ] || [ "$has_execution" = false ] || [ "$has_agents" = false ]; then
+    # Check if copilot-instructions already has evoskills entries
+    if ! grep -q "AI_CONSTITUTION.md" ".github/copilot-instructions.md" && \
+       ! grep -q "AI_INITIALIZATION.md" ".github/copilot-instructions.md" && \
+       ! grep -q "AGENTS.md" ".github/copilot-instructions.md"; then
+      # Only add if none of the evoskills references exist
       echo "" >> ".github/copilot-instructions.md"
-      echo "<!-- evoskills: auto-generated references -->" >> ".github/copilot-instructions.md"
-      
-      if [ "$has_constitution" = false ]; then
-        echo "- Please read and follow AI_CONSTITUTION.md (core evolution mechanism)" >> ".github/copilot-instructions.md"
-      fi
-      
-      if [ "$has_execution" = false ]; then
-        echo "- See EXECUTION_RULES.md for optional safety guardrails" >> ".github/copilot-instructions.md"
-      fi
-      
-      if [ "$has_agents" = false ]; then
-        echo "- Refer to AGENTS.md for skills registry" >> ".github/copilot-instructions.md"
-      fi
-      
-      print_success "Updated .github/copilot-instructions.md with evoskills references"
+      echo "## Embedded AI Skills Framework" >> ".github/copilot-instructions.md"
+      echo "" >> ".github/copilot-instructions.md"
+      echo "This project uses evoskills for AI-assisted development:" >> ".github/copilot-instructions.md"
+      echo "- `.github/AI_CONSTITUTION.md` - Core evolution mechanism (always active)" >> ".github/copilot-instructions.md"
+      echo "- `.github/AI_INITIALIZATION.md` - Mandatory 4-skill initialization protocol" >> ".github/copilot-instructions.md"
+      echo "- `AGENTS.md` - Skill registry (core, required system, and optional skills)" >> ".github/copilot-instructions.md"
+      print_success "Updated .github/copilot-instructions.md with evoskills framework"
     fi
   fi
 }
@@ -391,25 +432,35 @@ install_skill_github() {
   mkdir -p "$SKILLS_DIR/$skill"
 
   # Try to download SKILL.md and references from GitHub
-  if curl -sf "$skills_repo/raw/main/.agent/skills/$skill/SKILL.md" > "$SKILLS_DIR/$skill/SKILL.md" 2>/dev/null; then
+  local raw_url
+  raw_url=$(github_raw_url "$skills_repo" ".agent/skills/$skill/SKILL.md")
+  if curl -sf "$raw_url" > "$SKILLS_DIR/$skill/SKILL.md" 2>/dev/null; then
     print_success "Installed skill: $skill"
 
     # Try to download references/ if present
-    if curl -sf "$skills_repo/raw/main/.agent/skills/$skill/references/" &>/dev/null; then
+    local ref_url
+    ref_url=$(github_raw_url "$skills_repo" ".agent/skills/$skill/references/")
+    if curl -sf "$ref_url" &>/dev/null; then
       print_info "Downloading skill references..."
       mkdir -p "$SKILLS_DIR/$skill/references"
       # Download common reference files
       for ref_file in "*.md"; do
-        curl -sf "$skills_repo/raw/main/.agent/skills/$skill/references/$ref_file" > "$SKILLS_DIR/$skill/references/$ref_file" 2>/dev/null || true
+        local ref_file_url
+        ref_file_url=$(github_raw_url "$skills_repo" ".agent/skills/$skill/references/$ref_file")
+        curl -sf "$ref_file_url" > "$SKILLS_DIR/$skill/references/$ref_file" 2>/dev/null || true
       done
     fi
 
     # Try to download scripts/ if present
-    if curl -sf "$skills_repo/raw/main/.agent/skills/$skill/scripts/" &>/dev/null; then
+    local script_url
+    script_url=$(github_raw_url "$skills_repo" ".agent/skills/$skill/scripts/")
+    if curl -sf "$script_url" &>/dev/null; then
       print_info "Downloading skill scripts..."
       mkdir -p "$SKILLS_DIR/$skill/scripts"
       for script_file in "*.sh"; do
-        curl -sf "$skills_repo/raw/main/.agent/skills/$skill/scripts/$script_file" > "$SKILLS_DIR/$skill/scripts/$script_file" 2>/dev/null || true
+        local script_file_url
+        script_file_url=$(github_raw_url "$skills_repo" ".agent/skills/$skill/scripts/$script_file")
+        curl -sf "$script_file_url" > "$SKILLS_DIR/$skill/scripts/$script_file" 2>/dev/null || true
       done
     fi
   else
@@ -461,20 +512,29 @@ cmd_init() {
 
   ensure_layout
 
+  # Initialize config with default repository if not already set
+  local skills_repo
+  if [ -z "$custom_repo" ]; then
+    skills_repo="$DEFAULT_SKILLS_REPO"
+  else
+    skills_repo="$custom_repo"
+  fi
+
   cat > "$PROJECT_CONFIG_FILE" << EOF
 {
-  "version": "3.0.0",
+  "version": "3.1.0",
   "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "skillsDir": ".agent/skills",
   "openskillsCompatible": true,
-  "skillsRepo": "$(get_config_value 'skillsRepo')"
+  "skillsRepo": "$skills_repo"
 }
 EOF
 
   create_constitution_if_missing
-  create_execution_rules_if_missing
+  create_initialization_if_missing
   create_copilot_instructions_if_missing
 
+  print_success "Core framework files downloaded and verified"
   print_info "Installing core skills..."
   for skill in "${CORE_SKILLS[@]}"; do
     install_skill_github "$skill"
@@ -600,8 +660,8 @@ cmd_update() {
   fi
 
   ensure_layout
-  create_constitution_if_missing
-  create_execution_rules_if_missing
+  update_constitution
+  update_initialization
   create_copilot_instructions_if_missing
 
   if [ -n "$skill" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingyu.wang/evoskills",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Evolution Skills CLI for installing and managing openskills-compatible AI skills.",
   "license": "MIT",
   "bin": {