Tessl Workflow Installer

Implements Tessl skill review GitHub Actions workflows in your repository through an interactive, configuration-first wizard.

When to Use This Skill

Use this skill when you want to:

• Add Tessl skill review automation to a GitHub repository
• Update an existing Tessl workflow to v4 (score diff and caching)
• Migrate between single-workflow and two-workflow architectures

Overview

This skill walks you through three phases:

1. Validation & Discovery - Checks prerequisites, detects existing workflows
2. Configuration - Gathers your preferences with smart defaults
3. Execution - Creates files with confirmation at each step

Prerequisites

• Current directory must be a git repository
• Repository must have a GitHub remote configured
• You'll need to add TESSL_API_KEY to GitHub Secrets after setup

Workflow Architecture Options

Single-Workflow (Recommended for internal repositories)

• All contributors are trusted (private repos, company teams)
• Simpler setup with one workflow file
• Direct PR commenting with pull-requests: write permission

Two-Workflow (Recommended for public repositories)

• Accepts external contributions from untrusted forks
• Separates review from PR commenting for security
• Uses workflow_run trigger with secrets: inherit

Phase 1: Validation & Discovery

Step 1.1: Validate Git Repository

First, I'll check that we're in a valid git repository with a GitHub remote.

Actions:

1. Run git rev-parse --git-dir to verify git repository
2. Run git remote -v to check for GitHub remote
3. If either fails, exit with clear error message

Error Messages:

• Not a git repo: "❌ Current directory is not a git repository. Please run this skill from within your repository."
• No GitHub remote: "❌ No GitHub remote found. Please add a GitHub remote with: git remote add origin <url>"

Step 1.2: Detect Default Branch

Detect the repository's default branch from the GitHub remote.

Actions:

1. Run git remote show origin | grep 'HEAD branch' | cut -d' ' -f5
2. If that fails (e.g., no network), fall back to git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
3. If both fail, fall back to "main" with a warning: "⚠️ Could not detect default branch from remote. Defaulting to main."

Store result in: DEFAULT_BRANCH variable (e.g., "main", "master", "develop")

Display: "Detected default branch: {DEFAULT_BRANCH}"

Step 1.3: Detect Existing Workflows

Scan for existing Tessl skill review workflows and detect their version.

Actions:

1. Run find .github/workflows -name '*tessl*skill*review*.yml' -o -name '*tessl*skill*review*.yaml' 2>/dev/null
2. For each file found, read content and detect version:
   • v4: Contains both CACHE_ENTRIES_FILE and PREV_SCORE
   • v3: Contains --json and jq but no cache
   • v2: Contains tessl skill review with markdown table
   • v1: Basic implementation
   • Two-workflow: Has companion *comment*.yml with workflow_run
3. Store detection results in workflow state

Detection Patterns:

• v4 marker: grep -q "CACHE_ENTRIES_FILE" && grep -q "PREV_SCORE"
• v3 marker: grep -q "\-\-json" && grep -q "jq"
• Two-workflow: grep -q "workflow_run"

Step 1.4: Present Discovery Results

Show user what was found and offer appropriate path forward.

If no workflow found: "✅ No existing Tessl workflow detected. Ready to create a new one."

If v4 found: "✅ Found Tessl skill review workflow v4 (latest version).

Options: A) Keep existing workflow, skip to cache setup B) Recreate workflow (useful if you want to change architecture)

Which option?"

If v1-v3 found: "ℹ️ Found Tessl skill review workflow v{X}.

v4 adds:

• Score diff tracking (🔺 🔻 ➡️ indicators)
• Persistent cache in git
• Dimension-level score comparison

Update to v4?"

If architecture mismatch: "ℹ️ Found {current} workflow. You selected {new} architecture.

Migrate from {current} to {new}?

• This will {add/remove} the comment workflow file
• Existing cache data will be preserved"

Phase 2: Configuration

Step 2.1: Ask Workflow Architecture

Ask: "Which workflow architecture do you want?" (see Overview for details)

Options:

• Single-workflow (Recommended for internal repos) - Trusted contributors, simpler setup
• Two-workflow (Recommended for public repos) - External contributions, security isolation

Store answer in: WORKFLOW_ARCH variable (values: "single" or "two")

Step 2.2: Ask About Customization

Ask: "Use smart defaults, or customize settings?"

Current defaults:

• Target branch: {DEFAULT_BRANCH} (auto-detected from GitHub remote in Step 1.2)
• Trigger paths: **/SKILL.md, **/skills/**
• Cache location: .github/.tessl/skill-review-cache.json

Options:

• Use defaults - "Use these settings (recommended for most repos)"
• Customize - "Customize branch name, file paths, or cache location"

Store answer in: CUSTOMIZE variable (values: "defaults" or "customize")

If user chose defaults: Set TARGET_BRANCH to {DEFAULT_BRANCH} (the value detected in Step 1.2), TRIGGER_PATHS to **/SKILL.md, **/skills/**, and CACHE_FILE to .github/.tessl/skill-review-cache.json. Skip to Step 2.4.

Step 2.3: Gather Custom Settings (if customizing)

If user chose customize, ask follow-up questions:

Question 2.3a: Target Branch "Which branch should trigger workflow on push?"

• Default: {DEFAULT_BRANCH} (detected in Step 1.2)
• Options: {DEFAULT_BRANCH}, other (text input)

Question 2.3b: Trigger File Paths "Which file paths should trigger the workflow?"

• Default: **/SKILL.md, **/skills/**
• Options: Use defaults, Custom paths (text input)

Question 2.3c: Cache File Location "Where should the cache file be stored?"

• Default: .github/.tessl/skill-review-cache.json
• Options: Use default, Custom path (text input)

Store in variables:

• TARGET_BRANCH (default: {DEFAULT_BRANCH} from Step 1.2)
• TRIGGER_PATHS (default: "/SKILL.md', '/skills/**")
• CACHE_FILE (default: ".github/.tessl/skill-review-cache.json")

Step 2.4: Show Configuration Summary

Display configuration table and ask for approval:

📋 Configuration Summary

| Setting           | Value                                    |
|-------------------|------------------------------------------|
| Architecture      | {Single/Two}-workflow                    |
| Target Branch     | {TARGET_BRANCH}                          |
| Trigger Paths     | {TRIGGER_PATHS}                          |
| Cache Location    | {CACHE_FILE}                             |

Question: "Proceed with this configuration?"

Options:

• Approve - "Yes, create workflow with these settings"
• Go back - "No, let me change something"

If "Go back", restart from Step 2.1

Reference: Workflow Templates

The skill uses these battle-tested workflow templates with all fixes from v4 testing.

Template Variables

These placeholders are replaced with user's configuration:

• {{TARGET_BRANCH}} → User's target branch (default: auto-detected from GitHub remote)
• {{TRIGGER_PATHS}} → User's file paths (default: **/SKILL.md, /skills/)
• {{CACHE_FILE}} → User's cache location (default: .github/.tessl/skill-review-cache.json)

Single-Workflow Template

File: .github/workflows/tessl-skill-review.yml

Source: ./single-workflow.md (lines 27-479)

Note: This template is used for internal repositories where all contributors are trusted. It includes both review and PR commenting in a single workflow.

During execution: Read the complete YAML from the source documentation file, perform template variable substitution, and write to the target workflow file.

Two-Workflow Template (Main)

File: .github/workflows/tessl-skill-review.yml

Source: ./two-workflow.md (lines 87-545)

Note: This is the main review workflow for public repositories. It performs skill reviews and saves results as artifacts for the comment workflow.

During execution: Read the complete YAML from the source documentation file, perform template variable substitution, and write to the target workflow file.

Two-Workflow Template (Comment)

File: .github/workflows/tessl-skill-review-comment.yml

Source: ./two-workflow.md (lines 551-605)

Note: This workflow runs via workflow_run trigger to post PR comments. It inherits secrets securely for posting comments from untrusted forks.

During execution: Read the complete YAML from the source documentation file (no template substitution needed for this file), and write to the target workflow file.

Template Substitution Logic

When creating workflow files:

1. Read the appropriate template from the source documentation
2. Replace all occurrences:
   • branches: [main] → branches: [{{TARGET_BRANCH}}]
   • '**/SKILL.md' and '**/skills/**' → Replace with user's {{TRIGGER_PATHS}} (formatted as YAML array)
   • .github/.tessl/skill-review-cache.json → {{CACHE_FILE}}
3. Write the resulting YAML to the appropriate workflow file location

Phase 3: Execution

Interactive checklist with user confirmation at each step.

Step 3.1: Create/Update Workflow File(s)

Actions:

1. Create workflow directory if needed:

   mkdir -p .github/workflows

2. If updating existing workflow, create backup:

   BACKUP_DIR=".github/workflows/backup-$(date +%Y-%m-%d-%H%M%S)"
   mkdir -p "$BACKUP_DIR"
   mv .github/workflows/tessl-skill-review*.yml "$BACKUP_DIR/"

3. Generate workflow file(s) from templates:

   • Load appropriate template (single or two-workflow)
   • Replace {{TARGET_BRANCH}} with user's branch
   • Replace {{TRIGGER_PATHS}} with user's paths (properly YAML-formatted)
   • Replace {{CACHE_FILE}} with user's cache location
   • Write to .github/workflows/tessl-skill-review.yml
   • If two-workflow: Also write .github/workflows/tessl-skill-review-comment.yml

4. Confirm with user:

   ✅ Workflow file(s) created:
   - .github/workflows/tessl-skill-review.yml
   {- .github/workflows/tessl-skill-review-comment.yml}
   
   Continue to cache setup?

Step 3.2: Initialize/Update Cache File

Actions:

1. Check if cache file exists:

   if [ -f "{{CACHE_FILE}}" ]; then
     echo "Cache file already exists, skipping initialization"
   else
     # Create cache file
   fi

2. If creating new cache:

   # Create parent directory
   mkdir -p "$(dirname "{{CACHE_FILE}}")"
   
   # Create cache JSON
   cat > "{{CACHE_FILE}}" << 'EOF'
   {
     "version": "1",
     "last_updated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
     "skills": {}
   }
   EOF

3. Confirm with user:

   ✅ Cache file initialized at: {{CACHE_FILE}}
   
   Ready to proceed to API key reminder?

Step 3.3: Remind About API Key

Display:

⚠️  REQUIRED: Add TESSL_API_KEY to GitHub Secrets

Follow these steps:

1. Go to your repository on GitHub
2. Click: Settings → Secrets and variables → Actions
3. Click: "New repository secret"
4. Enter:
   - Name: TESSL_API_KEY
   - Value: <your Tessl API key from https://tessl.io>
5. Click: "Add secret"

The workflow will fail without this secret.

Ready to proceed to git operations?

Git Operations

After all files are created, ask the user what git operations to perform.

Step 4.1: Ask About Git Operations

Ask: "What would you like to do with these changes?"

Options:

A) Review changes first

• Shows: git status output
• Shows: git diff .github/ output
• Then asks again: "What next? (Stage / Commit / Exit)"

B) Stage files

• Runs: git add .github/workflows/tessl-skill-review*.yml
• Runs: git add {{CACHE_FILE}}
• Shows: "Files staged. Commit now? (Yes / No)"

C) Stage and commit

• Stages files as above
• Determines commit message based on context:
  • New installation: feat: add Tessl skill review workflow with score diff and caching
  • Update from v{X}: feat: update Tessl skill review workflow to v4 with score diff and caching
  • Migration: feat: migrate to {single/two}-workflow Tessl skill review
• Shows commit message preview
• Runs: git commit -m "<message>"
• Shows commit SHA
• Asks: "Push to remote? (Yes / No)"

D) Stage, commit, and push

• Executes all of option C
• Runs: git push
• Shows push result

E) Just show me the files, I'll handle git myself

• Lists created/modified files:

  Created files:
  - .github/workflows/tessl-skill-review.yml
  - {{CACHE_FILE}}
  
  You can stage them with:
  git add .github/workflows/tessl-skill-review*.yml {{CACHE_FILE}}

• Exits cleanly

Safety Notes

• Always use git add <specific-files> not git add .
• Show commit message before committing
• Confirm before pushing to remote
• Never force push

Testing Instructions

After setup is complete, refer to TESTING.md for:

• Quick test via manual workflow trigger
• Comprehensive PR flow test with score diff tracking
• Verification steps and common troubleshooting

Completion

✅ Tessl skill review workflow setup complete!

What you have now:

• {Single/Two}-workflow architecture configured
• Score diff tracking with persistent cache
• Auto-commit of cache updates
• PR comment integration

Next steps:

1. Add TESSL_API_KEY to GitHub Secrets (if not done)
2. Run the Quick Test to verify setup
3. Create a test PR to see the full workflow

Documentation:

• Single-workflow: single-workflow.md
• Two-workflow: two-workflow.md

Happy skill reviewing! 🎉