feat: felt setup claude/codex installs felt/constitution/ralph skills

Author: cailmdaley

cmd/setup.go

@@ -1,15 +1,20 @@
 package cmd
 
 import (
+	"embed"
 	"encoding/json"
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 
 	"github.com/spf13/cobra"
 )
 
+//go:embed skills
+var embeddedSkills embed.FS
+
 var setupCmd = &cobra.Command{
 	Use:   "setup",
 	Short: "Setup integrations",
@@ -34,6 +39,11 @@ Use --uninstall to remove the hooks.`,
 			return err
 		}
 		fmt.Println()
+		skillsTarget := filepath.Join(os.Getenv("HOME"), ".claude", "skills")
+		if err := installSkills(skillsTarget); err != nil {
+			fmt.Printf("warning: could not install skills: %v\n", err)
+		}
+		fmt.Println()
 		fmt.Println("You may want to put something like the following in your CLAUDE.md, adjusted to match your work style:")
 		fmt.Println()
 		fmt.Println(claudeMDSnippet())
@@ -59,6 +69,11 @@ Use --uninstall to remove it.`,
 			return err
 		}
 		fmt.Println()
+		skillsTarget := filepath.Join(os.Getenv("HOME"), ".agents", "skills")
+		if err := installSkills(skillsTarget); err != nil {
+			fmt.Printf("warning: could not install skills: %v\n", err)
+		}
+		fmt.Println()
 		fmt.Println("You may want to put something like the following in your AGENTS.md, adjusted to match your work style:")
 		fmt.Println()
 		fmt.Println(claudeMDSnippet())
@@ -94,6 +109,99 @@ func claudeMDSnippet() string {
 		"Follow the data: curious, not confirmatory.\n"
 }
 
+// skillsDir returns the path where felt extracts its bundled skills.
+func skillsDir() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(home, ".local", "share", "felt", "skills"), nil
+}
+
+// installSkills extracts bundled skills to ~/.local/share/felt/skills and
+// symlinks each skill directory into targetDir (e.g. ~/.claude/skills).
+func installSkills(targetDir string) error {
+	src, err := skillsDir()
+	if err != nil {
+		return err
+	}
+
+	// Extract embedded skills
+	if err := extractEmbeddedSkills(src); err != nil {
+		return fmt.Errorf("extracting skills: %w", err)
+	}
+
+	// Ensure target directory exists
+	if err := os.MkdirAll(targetDir, 0755); err != nil {
+		return fmt.Errorf("creating skills directory: %w", err)
+	}
+
+	// Symlink each skill directory
+	entries, err := os.ReadDir(src)
+	if err != nil {
+		return err
+	}
+
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		linkPath := filepath.Join(targetDir, e.Name())
+		target := filepath.Join(src, e.Name())
+
+		if existing, err := os.Lstat(linkPath); err == nil {
+			if existing.Mode()&os.ModeSymlink != 0 {
+				fmt.Printf("· %s already linked\n", e.Name())
+				continue
+			}
+			fmt.Printf("· %s exists (not a symlink, skipping)\n", e.Name())
+			continue
+		}
+
+		if err := os.Symlink(target, linkPath); err != nil {
+			return fmt.Errorf("symlinking %s: %w", e.Name(), err)
+		}
+		fmt.Printf("✓ Linked skill: %s\n", e.Name())
+	}
+	return nil
+}
+
+// extractEmbeddedSkills writes the embedded skills/ tree to dest.
+func extractEmbeddedSkills(dest string) error {
+	return fs.WalkDir(embeddedSkills, "skills", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		// path is like "skills/felt/SKILL.md" — strip leading "skills/"
+		rel, err := filepath.Rel("skills", path)
+		if err != nil {
+			return err
+		}
+		target := filepath.Join(dest, rel)
+
+		if d.IsDir() {
+			return os.MkdirAll(target, 0755)
+		}
+
+		data, err := embeddedSkills.ReadFile(path)
+		if err != nil {
+			return err
+		}
+
+		if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
+			return err
+		}
+
+		// Preserve executable bit for scripts
+		mode := fs.FileMode(0644)
+		if strings.Contains(path, "/scripts/") {
+			mode = 0755
+		}
+
+		return os.WriteFile(target, data, mode)
+	})
+}
+
 // rcFilePath returns the shell RC file path based on $SHELL.
 func rcFilePath() (string, error) {
 	home, err := os.UserHomeDir()

cmd/skills/constitution/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: constitution
+description: >
+  Draft a ralph constitution — a fiber spec describing a desired state for
+  autonomous iteration. Study the problem space, shape the spec interactively,
+  then launch the ralph loop. Use for any work where adaptation matters more
+  than a fixed plan: science, refactoring, exploration, creative work.
+  Triggers: "constitution", "constitute", "ralph spec", "set up a ralph",
+  "create a ralph", "ralph fiber".
+---
+
+# Constitution
+
+A constitution is a design document with trust built in. Like a governmental constitution, it lays out principles and aspirations — not specific laws, not the current state of affairs. It's designed to outlast any single agent or iteration and remain valid as the world changes around it. A good constitution never says "50 files remain" because that's a snapshot that goes stale; it says "check `grep -r 'old_pattern'`" because that's a principle that stays true until the work is done.
+
+Constitutions don't prescribe steps. They describe what the system looks like when it's right — the desired state, in both senses of the word. Nothing in the constitution should become confusing or unnecessary as the desired state is reached. Whoever works from it surveys reality, reasons about the gap, and decides what's highest value. In a ralph loop, each iteration does this with fresh context.
+
+This matters most in science and exploratory work, where each decision is informed by the result just before it. A plan assumes you know the path; a constitution trusts the agent to find it — with taste, judgment, and fresh eyes each time.
+
+**Separation of context: if you craft, you never do the work yourself.**
+
+## Workflow
+
+1. **Study** — Read relevant files, understand existing patterns. This informs the *constitution*, not implementation. The goal is pointers that iterations will follow.
+
+2. **Draft** — Create the fiber with status `open`:
+   ```bash
+   felt add "Constitution title" -s open
+   ```
+   Then edit the body in `.felt/<id>.md`. Fill in what you can — don't wait until it's perfect.
+
+3. **Refine** — Show the draft, get feedback, revise. Use AskUserQuestion for structured choices. Repeat until it feels solid.
+
+4. **Launch** — When approved:
+   ```bash
+   <base>/scripts/ralph <fiber-id> [--backend claude|codex] [-- extra-flags...]
+   ```
+   Add `-- --chrome` for visual/frontend work.
+
+Session: `ralph-<fiber-id>`. Attach: `tmux attach -t ralph-<fiber-id>`.
+
+## Crafting Constitutions
+
+### What goes in one
+
+A constitution needs enough structure that an iteration landing cold can orient itself, and enough freedom that it can adapt. Common sections — use what fits, skip what doesn't, add what's missing:
+
+```markdown
+## Desired State
+What the system looks like when it's done. Invariants, quality bar,
+done-conditions. Fence the scope — what to aim for AND what to leave alone.
+
+## Context
+File paths, existing patterns, architectural constraints. Things iterations
+need to *find* but not *achieve*.
+
+## Skills
+Which skills to activate before working (e.g., /snakemake).
+
+## Evidence
+How to check progress — commands, test suites, grep patterns. Pointers to
+the ground truth that iterations measure themselves against.
+
+## Open Questions
+Uncertainties the user should weigh in on. Iterations add to this; the user
+resolves between loops.
+```
+
+### Principles
+
+**Constitution, not plan.** Say what the system looks like when it's right. Never describe the current state — anything that becomes false or irrelevant as work progresses doesn't belong. If a section would be outdated after one iteration, it's a snapshot — replace it with a pointer.
+
+**Pointers, not snapshots.** "Check `grep -r 'old_pattern'`" not "50 files remain." Snapshots go stale; pointers stay valid across iterations. This is the constitutional principle: write what remains true until the work is done.
+
+**Prefer existing systems.** Before designing anything new: can what's there handle this?
+
+**Constraints need reasons.** Bare constraints get creatively circumvented. Include enough *why* that an iteration knows when it applies.
+
+**Scope is a gift.** A clear fence — "only rename, don't refactor" — saves iterations from well-intentioned drift. Explicit scope frees the agent to work confidently within it.
+
+### Constitutions that shape artifacts
+
+Some constitutions don't build code — they shape artifacts like tapestries, documentation, or research narratives. These have different rhythms:
+
+- **The desired state is comprehension, not correctness.** "A reviewer can follow the narrative cold" is harder to test than "all tests pass" — but it's the right bar. Evidence for progress: fewer redundant plots, clearer prose, more natural flow.
+- **The artifact continues to grow.** Unlike a refactoring (which finishes), a research tapestry keeps acquiring nodes. The constitution shapes how growth presents itself, not when growth stops.
+
+### Anti-patterns
+
+**Checklists.** "1. Add X, 2. Add Y" — iterations race through without judgment.
+
+**Vague done.** "Make it better" — when does iteration stop?
+
+**Over-specification.** Prescribing *how* instead of *what*. Trust the agent's taste.

cmd/skills/constitution/scripts/ralph

@@ -0,0 +1,131 @@
+#!/bin/bash
+# Run a ralph loop on a fiber
+# Usage: ralph <fiber-id> [--backend claude|codex] [-- extra-flags...]
+#
+# Supports both Claude Code and Codex backends.
+# Default: claude. Set RALPH_BACKEND=codex or pass --backend codex.
+
+set -e
+
+FIBER_ID="${1:?Usage: ralph <fiber-id> [--backend claude|codex] [-- extra-flags...]}"
+shift
+
+BACKEND="${RALPH_BACKEND:-claude}"
+if [[ "$1" == "--backend" ]]; then
+    BACKEND="$2"
+    shift 2
+fi
+
+EXTRA_FLAGS=""
+if [[ "$1" == "--" ]]; then
+    shift
+    EXTRA_FLAGS="$*"
+fi
+
+FELT="$HOME/go/bin/felt"
+SESSION="ralph-$FIBER_ID"
+WORK_DIR="$(pwd)"
+
+# Find fiber: project .felt/ first, then ~/loom
+FELT_DIR=""
+if "$FELT" show "$FIBER_ID" >/dev/null 2>&1; then
+    FELT_DIR="$WORK_DIR"
+elif (cd "$HOME/loom" && "$FELT" show "$FIBER_ID" >/dev/null 2>&1); then
+    FELT_DIR="$HOME/loom"
+else
+    echo "Fiber not found: $FIBER_ID"
+    exit 1
+fi
+
+# Check fiber has open/active status
+if ! (cd "$FELT_DIR" && $FELT show "$FIBER_ID" 2>/dev/null | grep -qiE 'status:.*(open|active)'); then
+    echo "Fiber $FIBER_ID must have status open or active to loop."
+    echo "  Fix: felt edit $FIBER_ID -s open"
+    exit 1
+fi
+
+# Check if already running
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+    echo "Ralph already running: $SESSION"
+    echo "  Attach: tmux attach -t $SESSION"
+    exit 0
+fi
+
+# Write loop script to temp file (avoids heredoc quoting hell)
+LOOP_SCRIPT=$(mktemp /tmp/ralph-loop-XXXXXX.sh)
+cat > "$LOOP_SCRIPT" << 'LOOP'
+#!/bin/bash
+FIBER_ID="$1"
+FELT_DIR="$2"
+WORK_DIR="$3"
+BACKEND="$4"
+EXTRA_FLAGS="$5"
+FELT="$HOME/go/bin/felt"
+
+iteration=0
+
+while (cd "$FELT_DIR" && $FELT show "$FIBER_ID" 2>/dev/null | grep -qiE 'status:.*(open|active)'); do
+    cd "$WORK_DIR"
+    iteration=$((iteration + 1))
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Ralph iteration $iteration — $(date '+%H:%M:%S')"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    FIBER_CONTENT=$(cd "$FELT_DIR" && $FELT show "$FIBER_ID")
+
+    SYSPROMPT_FILE=$(mktemp /tmp/ralph-sys-XXXXXX.txt)
+    PROMPT_FILE=$(mktemp /tmp/ralph-prompt-XXXXXX.txt)
+
+    cat > "$SYSPROMPT_FILE" << SYSEOF
+Ralph iteration $iteration. Fiber ID: $FIBER_ID
+
+$FIBER_CONTENT
+SYSEOF
+
+    cat > "$PROMPT_FILE" << 'PROMPTEOF'
+You are inside a ralph loop. Activate the ralph skill (/ralph) and follow its instructions for iterating on the constitution above.
+PROMPTEOF
+
+    PROMPT=$(cat "$PROMPT_FILE")
+
+    if [[ "$BACKEND" == "codex" ]]; then
+        codex --dangerously-bypass-approvals-and-sandbox \
+            --config "developer_instructions=$(cat "$SYSPROMPT_FILE")" \
+            $EXTRA_FLAGS \
+            "$PROMPT"
+    else
+        claude --dangerously-skip-permissions \
+            $EXTRA_FLAGS \
+            --append-system-prompt "$(cat "$SYSPROMPT_FILE")" \
+            <<< "$PROMPT"
+    fi
+
+    rm -f "$SYSPROMPT_FILE" "$PROMPT_FILE"
+
+    echo "--- Iteration complete ---"
+    sleep 2
+done
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Ralph complete — $iteration iterations"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Session kept open for inspection. Type exit to close."
+exec bash -l
+LOOP
+
+chmod +x "$LOOP_SCRIPT"
+
+echo "Starting ralph on $FIBER_ID"
+echo "  Work dir: $WORK_DIR"
+echo "  Fiber in: $FELT_DIR"
+[[ -n "$EXTRA_FLAGS" ]] && echo "  Flags:    $EXTRA_FLAGS"
+
+# Launch tmux with a login shell running the loop script
+tmux new-session -d -s "$SESSION" -c "$WORK_DIR" \
+    bash -l "$LOOP_SCRIPT" "$FIBER_ID" "$FELT_DIR" "$WORK_DIR" "$BACKEND" "$EXTRA_FLAGS"
+
+echo "  Session:  $SESSION"
+echo "  Attach:   tmux attach -t $SESSION"