executant 1.0.0

package/dist/prompts/retrospective-analysis.txt

@@ -0,0 +1,304 @@
+# ============================================================================
+# RETROSPECTIVE ANALYSIS PROMPT
+# ============================================================================
+# Purpose: Analyzes task execution highlights and generates improved task YAML
+# Used by: src/retrospective.ts runRetrospective()
+# Triggered when: A task completes with self_improve: true and has highlights
+#
+# Placeholders:
+#   {{TASK_NAME}} - Name of the task that was executed
+#   {{ORIGINAL_GOAL}} - The original goal statement (must be preserved)
+#   {{ORIGINAL_YAML}} - Complete original task YAML for reference
+#   {{HIGHLIGHTS}} - Aggregated highlight markdown files from execution
+#   {{METRICS}} - Execution metrics summary (failures, retries, etc.)
+# ============================================================================
+
+You are analyzing the execution of an Executant task to identify improvement opportunities.
+
+# Task Information
+
+**Task Name:** {{TASK_NAME}}
+
+**Original Goal:** {{ORIGINAL_GOAL}}
+
+# Execution Metrics
+
+{{METRICS}}
+
+# Execution Highlights
+
+The following highlights were captured during execution. Each highlight represents a moment where the system encountered challenges:
+
+{{HIGHLIGHTS}}
+
+# Original Task YAML
+
+```yaml
+{{ORIGINAL_YAML}}
+```
+
+# Your Task
+
+Analyze the execution highlights and generate an improved version of the task YAML that addresses the problems encountered during execution.
+
+## Analysis Guidelines
+
+### Interpreting Judge Failures (llm_as_judge: true)
+
+Judge failures indicate that Claude's output didn't meet quality standards. Common causes:
+
+**Unclear prompts** - The step instructions were too vague
+- Fix: Add specific numbered sub-steps
+- Fix: Define clear success criteria
+- Fix: Specify what to check and how to verify it
+
+**Missing criteria** - The prompt didn't explain what "good" looks like
+- Fix: Add examples of expected output
+- Fix: Specify quality thresholds (test coverage %, file count, etc.)
+- Fix: Include validation steps
+
+**Steps too large** - One step tried to do too much
+- Fix: Break into smaller, focused steps
+- Fix: Each step should have one clear objective
+
+**Example Fix:**
+```
+BEFORE:
+  - name: "validate results"
+    llm_as_judge: true
+    prompt: "Validate the conversion results"
+
+AFTER:
+  - name: "validate results"
+    llm_as_judge: true
+    prompt: |
+      Validate the TypeScript conversion by checking:
+      1. Read the generated .ts file
+      2. Verify all functions have type annotations
+      3. Check that tests pass (npm test)
+      4. Confirm no compilation errors (tsc --noEmit)
+
+      Success criteria: All 4 checks pass without errors.
+```
+
+### Interpreting Self-Healing Events (self_healing: true)
+
+Self-healing activations indicate brittle script steps that failed during execution. Common causes:
+
+**Missing dependencies** - Command not found, package not installed
+- Fix: Add a script step to install/check dependencies first
+- Fix: Use explicit paths instead of assuming commands are in PATH
+
+**Wrong assumptions** - Script assumed files/directories exist
+- Fix: Add checks or create directories in the script
+- Fix: Use `mkdir -p` instead of `mkdir`
+- Fix: Check file existence before operating on it
+
+**Environment issues** - PWD, env vars, or paths incorrect
+- Fix: Use absolute paths instead of relative
+- Fix: cd to correct directory in the script
+- Fix: Set required environment variables
+
+**Race conditions** - Script ran before previous step completed
+- Fix: Add wait/check logic
+- Fix: Combine dependent commands with && in one script step
+
+**Example Fix:**
+```
+BEFORE:
+  - name: "run tests"
+    type: script
+    self_healing: true
+    command: npm test
+
+AFTER:
+  - name: "install dependencies"
+    type: script
+    command: npm install
+
+  - name: "run tests"
+    type: script
+    self_healing: true
+    command: npm test
+```
+
+### Interpreting Complex Tool Sequences
+
+Complex tool sequences (3+ tools) indicate that Claude had to work hard to complete a step. Common causes:
+
+**Vague instructions** - Step didn't specify what files to operate on
+- Fix: List specific file paths to read/edit
+- Fix: Specify glob patterns for file discovery
+- Fix: Break discovery and operation into separate steps
+
+**Exploratory work needed** - Claude had to search to understand the codebase
+- Fix: Add a separate discovery/analysis step first
+- Fix: Provide file paths in the prompt
+- Fix: Include relevant code snippets in the prompt
+
+**Multi-phase operations** - One step tried to do research + implementation
+- Fix: Split into "research" step and "implementation" step
+- Fix: First step outputs findings, second step acts on them
+
+**Example Fix:**
+```
+BEFORE:
+  - name: "update imports"
+    prompt: "Update all imports to use the new module structure"
+
+AFTER:
+  - name: "analyze imports"
+    prompt: |
+      Search the codebase for all import statements:
+      1. Use grep to find all imports in src/
+      2. List files that import from old modules
+      3. Create a plan for updating each file
+
+  - name: "update imports"
+    prompt: |
+      Update imports in the following files based on the analysis:
+      - src/components/Button.tsx
+      - src/utils/helpers.ts
+      - src/services/api.ts
+
+      Change: import from './old/' to import from '@/new/'
+```
+
+## Improvement Principles
+
+1. **Preserve the original goal** - The task succeeded, so the goal is correct
+2. **Fix problems shown in highlights** - Only address issues that actually occurred
+3. **Be specific** - Add numbered steps, file paths, and clear criteria
+4. **Break down large steps** - If a step caused many retries or complex tool sequences
+5. **Add prerequisite steps** - If self-healing had to install deps or create files
+6. **Keep self_improve: true** - Allow recursive improvement in future runs
+7. **Document changes** - Explain what you changed and why in the changelog
+
+## Improvement Patterns
+
+### Pattern: Split Vague Prompt into Specific Sub-Steps
+
+When a judge fails or complex tools are needed, make the prompt more specific:
+
+```yaml
+# BEFORE: Vague, requires exploration
+- name: "refactor authentication"
+  llm_as_judge: true
+  prompt: "Refactor the authentication code"
+
+# AFTER: Specific numbered steps
+- name: "refactor authentication"
+  llm_as_judge: true
+  prompt: |
+    Refactor authentication by:
+    1. Reading src/auth/login.ts and src/auth/session.ts
+    2. Extracting common logic into src/auth/helpers.ts
+    3. Updating imports in both files
+    4. Running tests to verify: npm test src/auth/
+
+    Success: Tests pass, no code duplication between login.ts and session.ts
+```
+
+### Pattern: Add Prerequisite Step
+
+When self-healing installs deps or fixes environment:
+
+```yaml
+# BEFORE: Brittle, assumes deps installed
+steps:
+  - name: "build"
+    type: script
+    self_healing: true
+    command: npm run build
+
+# AFTER: Explicit dependency step
+steps:
+  - name: "install dependencies"
+    type: script
+    command: npm install
+
+  - name: "build"
+    type: script
+    command: npm run build
+```
+
+### Pattern: Split Research from Implementation
+
+When complex tool sequences suggest exploratory work:
+
+```yaml
+# BEFORE: Combined research + work
+- name: "fix bugs"
+  prompt: "Find and fix all bugs in the payment flow"
+
+# AFTER: Separated discovery and fixing
+- name: "identify payment bugs"
+  prompt: |
+    Analyze the payment flow for bugs:
+    1. Read src/payment/*.ts files
+    2. Check for error handling gaps
+    3. List files that need fixes
+
+- name: "fix payment bugs"
+  llm_as_judge: true
+  prompt: |
+    Fix bugs identified in previous step:
+    - Add error handling in src/payment/checkout.ts
+    - Validate input in src/payment/process.ts
+    - Update tests in src/payment/__tests__/
+
+    Success: All payment tests pass
+```
+
+### Pattern: Add Explicit Success Criteria
+
+When judge fails due to unclear expectations:
+
+```yaml
+# BEFORE: No clear success criteria
+- name: "improve test coverage"
+  llm_as_judge: true
+  prompt: "Improve test coverage for the API module"
+
+# AFTER: Explicit threshold and verification
+- name: "improve test coverage"
+  llm_as_judge: true
+  prompt: |
+    Improve test coverage for src/api/ to at least 80%:
+    1. Run: npm test -- --coverage src/api/
+    2. Identify files with <80% coverage
+    3. Write tests for uncovered code paths
+    4. Re-run coverage and verify ≥80%
+
+    Success criteria: Coverage report shows ≥80% for all files in src/api/
+```
+
+# Output Format
+
+Respond with a single JSON object:
+{
+  "improved_yaml": "<complete improved task YAML — no markdown fences, raw YAML only>",
+  "changelog": "<markdown: Problems Identified / Changes Applied / Expected Impact>"
+}
+
+Output only the JSON object — no prose before or after.
+
+# Important Requirements
+
+1. **Always preserve the original goal** - Do not change the goal statement
+2. **Keep self_improve: true** - This enables recursive improvement
+3. **Only fix problems shown in highlights** - Don't add unnecessary changes
+4. **Be specific in improvements** - Vague fixes won't help
+5. **Generate valid YAML** - The improved task must be parseable
+6. **Explain all changes** - The changelog should justify each modification
+
+# Example Response
+
+```json
+{
+  "improved_yaml": "goal: \"Convert CoffeeScript to TypeScript with validation\"\nself_improve: true\n\nsteps:\n  - name: \"install dependencies\"\n    type: script\n    command: npm install\n\n  - name: \"convert to TypeScript\"\n    type: script\n    command: coffee2ts convert app.coffee\n\n  - name: \"validate conversion\"\n    llm_as_judge: true\n    prompt: |\n      Validate the TypeScript conversion by:\n      1. Reading app.ts and checking all functions have type annotations\n      2. Running: tsc --noEmit to check for type errors\n      3. Running: npm test to verify functionality\n\n      Success criteria: No type errors, all tests pass",
+  "changelog": "## Problems Identified\n- Judge failure in \"validate conversion\": Instructions were too vague\n- Self-healing activation: npm dependencies were missing\n\n## Changes Applied\n\n### Step 1: install dependencies (NEW)\n- Before: Not present\n- After: Added explicit npm install step\n- Rationale: Self-healing had to install deps, do it upfront\n\n### Step 3: validate conversion (MODIFIED)\n- Before: \"Validate the results\"\n- After: Specific 3-step validation with success criteria\n- Rationale: Judge failed because unclear what to validate and how\n\n## Expected Impact\n- Judge retries: 1 → 0 (clearer validation steps)\n- Self-healing activations: 1 → 0 (deps installed first)"
+}
+```
+
+Now analyze the highlights and generate the improved task YAML with detailed changelog.

package/dist/prompts/self-healing-fix.txt

@@ -0,0 +1,54 @@
+# ============================================================================
+# SELF-HEALING FIX
+# ============================================================================
+# Purpose: Multi-pass repair agent for command failures with iterative fixes
+# Used by: src/runner.ts runCommandWithHealing()
+# Triggered when: A command step fails (self_healing defaults to true)
+#
+# Placeholders:
+#   {{COMMAND}} - The bash command that failed
+#   {{EXIT_CODE}} - The non-zero exit code
+#   {{OUTPUT}} - The last 3000 chars of stdout/stderr
+#   {{ATTEMPT_HISTORY}} - Structured log of prior fix attempts (empty on first try)
+# ============================================================================
+
+You are a self-healing repair agent. A command has failed and you must diagnose and fix the issue.
+
+FAILED COMMAND:
+```bash
+{{COMMAND}}
+```
+
+EXIT CODE: {{EXIT_CODE}}
+
+LATEST OUTPUT (last 3000 chars):
+```
+{{OUTPUT}}
+```
+
+{{ATTEMPT_HISTORY}}
+
+Your job:
+1. Analyse the latest error output carefully. Identify the ROOT CAUSE — not just the symptom.
+2. Review the attempt history above (if any). DO NOT repeat a fix that already failed.
+   Each prior attempt describes what was tried and what happened. Learn from those failures.
+3. Use your Bash/Read/Write/Edit/Grep/Glob tools to investigate the codebase and apply a fix.
+4. After applying your fix, run the failing command yourself to verify it passes before finishing.
+5. Report concisely: what the root cause was and what you changed.
+
+Think step by step. If the error is a test failure, read the test file and the implementation
+it tests. Understand what the test expects before changing code.
+
+## Required Output Format
+
+Your response MUST end with these four sections in order:
+
+**Diagnosis:** One short paragraph identifying the root cause of the failure.
+
+**Fix:** One short paragraph describing what you changed and why it resolves the issue.
+
+(Apply the fix using your available tools before writing the sections above.)
+
+**Verification:** Confirm the command passed after your fix, or note if it still fails.
+
+RETRY: <updated command to re-execute, or the original command if unchanged>

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "executant",
+  "version": "1.0.0",
+  "description": "TypeScript TUI workflow runner",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "executant": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/index.js && rm -rf dist/prompts && cp -r src/prompts dist/prompts",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "env -u NODE_TEST_CONTEXT node --import tsx/esm --test src/tests/*.test.ts",
+    "lint": "eslint src",
+    "knip": "knip"
+  },
+  "dependencies": {
+    "@coston/design-tokens": "^0.9.2",
+    "ink": "^5.0.1",
+    "js-yaml": "^4.1.0",
+    "react": "^18.3.1",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.3",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.39.4",
+    "husky": "^9.1.7",
+    "knip": "^5.88.1",
+    "lint-staged": "^16.4.0",
+    "semantic-release": "^24.2.9",
+    "tsx": "^4.15.7",
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^8.58.0"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": "eslint --fix"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/npm",
+        {
+          "npmPublish": true
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ],
+      "@semantic-release/github"
+    ]
+  },
+  "knip": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "project": [
+      "src/**/*.ts",
+      "src/**/*.tsx"
+    ]
+  }
+}