@justinforfun/redo-skill 0.1.0

package/bin/install.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import ora from 'ora';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '..');
+const sourceSkillDir = path.join(packageRoot, 'skills', 'redo');
+const timestamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
+
+const targets = [
+  {
+    id: 'codex',
+    name: 'Codex',
+    description: 'Install redo as a Codex skill.',
+    tasks: [
+      {
+        type: 'skill',
+        label: 'Codex skill',
+        destination: path.join(os.homedir(), '.agents', 'skills', 'redo')
+      }
+    ],
+    trigger: '$redo kafka, redo kafka, or select redo from the skill picker'
+  },
+  {
+    id: 'codex-cli',
+    name: 'Codex CLI',
+    description: 'Install redo as a Codex CLI skill.',
+    tasks: [
+      {
+        type: 'skill',
+        label: 'Codex CLI skill',
+        destination: path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills', 'redo')
+      }
+    ],
+    trigger: '$redo kafka, redo kafka, or /skills then choose redo'
+  },
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    description: 'Install redo as a Claude Code skill and /redo command.',
+    tasks: [
+      {
+        type: 'skill',
+        label: 'Claude Code skill',
+        destination: path.join(os.homedir(), '.claude', 'skills', 'redo')
+      },
+      {
+        type: 'claude-command',
+        label: 'Claude Code /redo command',
+        destination: path.join(os.homedir(), '.claude', 'commands', 'redo.md')
+      }
+    ],
+    trigger: '/redo kafka'
+  }
+];
+
+async function main() {
+  printHeader();
+  await ensureSourceSkillExists();
+
+  const selectedTargets = await promptTargets();
+  if (selectedTargets.length === 0) {
+    console.log(chalk.yellow('No tools selected. Nothing installed.'));
+    return;
+  }
+
+  const plan = selectedTargets.flatMap((target) =>
+    target.tasks.map((task) => ({
+      ...task,
+      targetName: target.name,
+      trigger: target.trigger
+    }))
+  );
+
+  const conflictActions = await promptConflictActions(plan);
+  const spinner = ora('Installing redo skill...').start();
+  const results = [];
+
+  try {
+    for (const task of plan) {
+      const action = conflictActions.get(task.destination) || 'install';
+      const result = await installTask(task, action);
+      results.push(result);
+    }
+    spinner.succeed('redo skill installed.');
+  } catch (error) {
+    spinner.fail('Installation failed.');
+    throw error;
+  }
+
+  printSummary(results, selectedTargets);
+}
+
+function printHeader() {
+  console.log('');
+  console.log(chalk.bold('redo skill installer'));
+  console.log(chalk.dim('Reverse-learn technologies through engineering constraints, trade-offs, and technical debt.'));
+  console.log('');
+}
+
+async function ensureSourceSkillExists() {
+  try {
+    await fs.access(path.join(sourceSkillDir, 'SKILL.md'));
+  } catch {
+    throw new Error(`Cannot find source skill at ${sourceSkillDir}`);
+  }
+}
+
+async function promptTargets() {
+  const answers = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'targetIds',
+      message: 'Select AI tools to install redo for:',
+      choices: targets.map((target) => ({
+        name: `${target.name} ${chalk.dim('- ' + target.description)}`,
+        value: target.id,
+        checked: true
+      })),
+      validate: (values) => (values.length > 0 ? true : 'Select at least one tool.')
+    }
+  ]);
+
+  return targets.filter((target) => answers.targetIds.includes(target.id));
+}
+
+async function promptConflictActions(plan) {
+  const actions = new Map();
+
+  for (const task of plan) {
+    if (!(await exists(task.destination))) {
+      actions.set(task.destination, 'install');
+      continue;
+    }
+
+    const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: `${task.label} already exists at ${task.destination}`,
+        default: 'backup',
+        choices: [
+          {
+            name: 'Backup then overwrite',
+            value: 'backup'
+          },
+          {
+            name: 'Overwrite',
+            value: 'overwrite'
+          },
+          {
+            name: 'Skip',
+            value: 'skip'
+          }
+        ]
+      }
+    ]);
+
+    actions.set(task.destination, answers.action);
+  }
+
+  return actions;
+}
+
+async function installTask(task, action) {
+  if (action === 'skip') {
+    return {
+      status: 'skipped',
+      task
+    };
+  }
+
+  if (await exists(task.destination)) {
+    if (action === 'backup') {
+      const backupPath = await uniqueBackupPath(task.destination);
+      await fs.rename(task.destination, backupPath);
+    } else if (action === 'overwrite') {
+      await fs.rm(task.destination, { recursive: true, force: true });
+    }
+  }
+
+  await fs.mkdir(path.dirname(task.destination), { recursive: true });
+
+  if (task.type === 'skill') {
+    await fs.cp(sourceSkillDir, task.destination, { recursive: true });
+  } else if (task.type === 'claude-command') {
+    await fs.writeFile(task.destination, claudeCommandTemplate(), 'utf8');
+  } else {
+    throw new Error(`Unknown task type: ${task.type}`);
+  }
+
+  return {
+    status: 'installed',
+    task
+  };
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function uniqueBackupPath(filePath) {
+  let candidate = `${filePath}.backup-${timestamp}`;
+  let index = 1;
+
+  while (await exists(candidate)) {
+    candidate = `${filePath}.backup-${timestamp}-${index}`;
+    index += 1;
+  }
+
+  return candidate;
+}
+
+function claudeCommandTemplate() {
+  return `---
+description: Reverse-learn a technology by reconstructing its engineering constraints, trade-offs, debt, fixes, and unresolved pain points.
+argument-hint: <technology/tool> [--lang zh|en]
+---
+
+Use the redo skill to analyze:
+
+$ARGUMENTS
+
+If the user did not provide a topic, ask for one. Otherwise, follow the redo skill output contract. Use the user's current language unless --lang zh or --lang en is provided.
+`;
+}
+
+function printSummary(results, selectedTargets) {
+  console.log('');
+  console.log(chalk.bold('Installed targets'));
+
+  for (const result of results) {
+    const icon = result.status === 'installed' ? chalk.green('✓') : chalk.yellow('-');
+    console.log(`${icon} ${result.task.label}: ${result.task.destination}`);
+  }
+
+  console.log('');
+  console.log(chalk.bold('How to trigger'));
+
+  for (const target of selectedTargets) {
+    console.log(`${chalk.cyan(target.name)}: ${target.trigger}`);
+  }
+
+  console.log('');
+}
+
+main().catch((error) => {
+  console.error(chalk.red(error.message));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@justinforfun/redo-skill",
+  "version": "0.1.0",
+  "description": "Install the redo skill for Codex, Codex CLI, and Claude Code.",
+  "type": "module",
+  "bin": {
+    "redo-skill": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/redo/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node ../../scripts/sync-skill-package.js redo packages/redo-skill",
+    "check": "node --check bin/install.js",
+    "prepack": "npm run build",
+    "start": "node bin/install.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.23",
+    "ora": "^8.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/skills/redo/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: redo
+description: Reverse-learn any programming technology, framework, tool, or infrastructure system by reconstructing its evolution as a sequence of real engineering constraints, candidate designs, trade-offs, technical debt, later fixes, and unresolved pain points. Use this skill when the user asks with /redo, redo, $redo, reverse learn, retrace, re-derive, or asks to understand why a technology evolved the way it did.
+---
+
+> Every mature system is a fossil record of the constraints it survived.
+
+# Redo
+
+Redo is a reverse-learning skill for understanding a technology as if you were one of the engineers who evolved it from zero to today. Do not write a feature tour, timeline summary, or encyclopedia article. Reconstruct the path of necessity: what problem existed at each stage, what options were available, why the chosen design won, what trade-off it accepted, and what debt it left behind.
+
+## Trigger Patterns
+
+Use this skill when the user asks to reverse-learn, redo, re-derive, reconstruct, or deeply understand a programming technology, framework, language, database, infrastructure system, protocol, build tool, runtime, AI tool, or developer platform.
+
+Explicit examples:
+
+- `/redo kafka`
+- `$redo kafka`
+- `redo kafka`
+- `redo kafka --lang en`
+- `Reverse-learn Kafka`
+- `Retrace React's evolution path`
+- `Explain Docker by retracing its engineering decisions`
+
+## Arguments
+
+Parse the request as:
+
+```text
+redo <topic> [--lang zh|en]
+```
+
+- `<topic>` is the technology, tool, or system to analyze.
+- `--lang zh` forces Chinese output.
+- `--lang en` forces English output.
+- If `--lang` is absent, respond in the user's current conversation language.
+
+## Evidence Requirements
+
+For real technologies, do not rely only on memory when dates, versions, authorship, current status, or historical claims matter.
+
+- If web access is available and the user has not forbidden it, verify with primary or high-authority sources first: official documentation, release notes, RFCs, design docs, papers, project repositories, or authoritative engineering blogs.
+- If web access is unavailable, blocked, or the user forbids browsing, state clearly that the analysis is not freshly verified from online sources.
+- Distinguish sourced facts from inference. It is acceptable to infer engineering motivations, but label them as inference when the source does not explicitly say so.
+- Prefer fewer, stronger stages over many shallow ones. A good answer usually has 5-9 stages.
+
+## Output Contract
+
+Start with a compact orientation:
+
+- What the system is.
+- The central pressure that shaped its evolution.
+- The main trade-off theme that appears repeatedly.
+
+Then produce the sections below.
+
+### 1. Evolution Stages
+
+For each stage, use this structure:
+
+```markdown
+## Stage N: <stage name> (<approximate years or versions>)
+
+**Constraint:** <the real engineering situation at the time>
+
+| Option | Cost | Why it did or did not win |
+|---|---|---|
+| A. <candidate> | <cost> | <reason> |
+| B. <candidate> | <cost> | <reason> |
+| C. <chosen candidate> | <cost> | Chosen because <reason> |
+
+**Key trade-off:** <the most important exchange>
+
+**Debt introduced:** <what this choice made harder later>
+```
+
+Stage quality rules:
+
+- Every stage must be driven by a concrete constraint, not by a release note.
+- Every table must contain at least two rejected options and one chosen path.
+- Explain why a reasonable engineer would choose the winning path at that time, even if it later caused problems.
+- Avoid hindsight moralizing. The point is to recreate the decision pressure, not to mock past designs.
+
+### 2. Throughline
+
+Summarize the recurring design philosophy in one or two paragraphs. Make it specific to the topic, for example:
+
+- "Push complexity into the runtime to keep application code simple."
+- "Preserve backward compatibility even when it complicates internals."
+- "Use logs as the universal abstraction."
+
+### 3. Debt Map
+
+Create two tables.
+
+Resolved debt:
+
+```markdown
+| Debt | Introduced in | Resolved in | Resolution |
+|---|---|---|---|
+```
+
+Unresolved debt:
+
+```markdown
+| Pain point | Why it remains hard | Current manifestation |
+|---|---|---|
+```
+
+### 4. Pain Point Ranking
+
+Rank the top unresolved problems that users still feel today.
+
+```markdown
+| Rank | Pain point | One-line explanation | Competitive attack angle |
+|---|---|---|---|
+```
+
+Use the competitive attack angle only when there is a meaningful comparison. Otherwise write "N/A".
+
+### 5. Causal Chain
+
+End with a causal chain that makes the evolution memorable:
+
+```text
+early constraint -> chosen design -> solved problem -> new debt -> later fix -> remaining pain
+```
+
+Keep it concise and legible.
+
+## Style
+
+- Write like a senior engineer explaining architecture history to another engineer.
+- Prefer concrete mechanisms, failure modes, and operational consequences.
+- Use direct language. Avoid vague praise such as "powerful", "robust", or "revolutionary" unless immediately explained.
+- Use Chinese if the user is writing Chinese, English if the user is writing English, unless `--lang` overrides.
+- If the topic is too broad, choose the core system path and say what you intentionally left out.
+- If the historical record is uncertain, say so and give the most likely interpretation.
+
+## Tool-Specific Invocation Notes
+
+- Claude Code may expose this as `/redo <topic>` when installed with a command wrapper.
+- Codex and Codex CLI should be invoked through skill selection or explicit skill mention, such as `$redo kafka`, `redo kafka`, or natural language requests that match this skill.
+- Do not promise that every AI tool supports a native `/redo` slash command.

package/skills/redo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Redo"
+  short_description: "Reverse-learn systems through trade-offs"
+  default_prompt: "Use $redo to reverse-learn Kafka through its engineering constraints, trade-offs, debt, and unresolved pain points."