From d5b5deb57df003c8fadbbee2a4b62d6329785700 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Tue, 17 Mar 2026 01:53:16 -0600 Subject: [PATCH 1/2] docs: add /titan-forge skill for executing sync plans MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the FORGE phase to the Titan Paradigm — reads sync.json produced by /titan-sync and executes it one phase at a time: understands each target with codegraph, makes the refactoring change, validates with /titan-gate, commits, and advances state. Resumable across sessions. --- .claude/skills/titan-forge/SKILL.md | 242 ++++++++++++++++++ docs/examples/claude-code-skills/README.md | 29 ++- .../claude-code-skills/titan-forge/SKILL.md | 242 ++++++++++++++++++ 3 files changed, 502 insertions(+), 11 deletions(-) create mode 100644 .claude/skills/titan-forge/SKILL.md create mode 100644 docs/examples/claude-code-skills/titan-forge/SKILL.md diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md new file mode 100644 index 00000000..03a2f628 --- /dev/null +++ b/.claude/skills/titan-forge/SKILL.md @@ -0,0 +1,242 @@ +--- +name: titan-forge +description: Execute the sync.json plan — refactor code, validate with /titan-gate, commit, and advance state (Titan Paradigm Phase 4) +argument-hint: <--phase N> <--target name> <--dry-run> +allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Agent +--- + +# Titan FORGE — Execute Sync Plan + +You are running the **FORGE** phase of the Titan Paradigm. + +Your goal: read `sync.json`, find the next incomplete execution phase, make the actual code changes for each target, validate with `/titan-gate`, commit, and advance state. + +> **Context budget:** One phase per invocation. Do not attempt all phases in one session — the context window will fill. Run one phase, report, stop. User re-runs for the next phase. + +**Arguments** (from `$ARGUMENTS`): +- No args → run next incomplete phase +- `--phase N` → jump to specific phase +- `--target ` → run single target only (for retrying failures) +- `--dry-run` → show what would be done without changing code + +--- + +## Step 0 — Pre-flight + +1. **Worktree check:** + ```bash + git rev-parse --show-toplevel && git worktree list + ``` + If not in a worktree, stop: "Run `/worktree` first." + +2. **Sync with main:** + ```bash + git fetch origin main && git merge origin/main --no-edit + ``` + If there are merge conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run `/titan-forge`." + +3. **Load artifacts.** Read: + - `.codegraph/titan/sync.json` — execution plan (if missing: "Run `/titan-sync` first.") + - `.codegraph/titan/titan-state.json` — current state + - `.codegraph/titan/gauntlet.ndjson` — per-target audit details + - `.codegraph/titan/gauntlet-summary.json` — aggregated results + +4. **Validate state.** If `titan-state.json` has `currentPhase` other than `"sync"` and no existing `execution` block, stop: "State not ready. Run `/titan-sync` first." + +5. **Initialize execution state** (if first run). Add to `titan-state.json`: + ```json + { + "execution": { + "currentPhase": 1, + "completedPhases": [], + "currentTarget": null, + "completedTargets": [], + "failedTargets": [], + "commits": [] + } + } + ``` + +6. **Determine next phase.** Use `--phase N` if provided, otherwise find the lowest phase number not in `completedPhases`. + +7. **Print plan:** + > Phase N: \ — N targets, estimated N commits + +8. **Ask for confirmation** before starting (unless `$ARGUMENTS` contains `--yes`). + +--- + +## Step 1 — Phase-specific execution strategies + +Each phase type requires different code-change logic: + +### Phase 1: Dead code cleanup +- Delete the symbol/export +- Verify no consumers: `codegraph fn-impact -T --json` +- Remove any orphaned imports +- Run lint to clean up + +### Phase 2: Shared abstractions +- Extract function/interface to new or existing file +- Update imports in all consumers +- Verify with: `codegraph exports -T --json` + +### Phase 3: Empty catches / error handling +- Replace `catch {}` with `catch (e) { logger.debug(...) }` or explicit fallback +- Use contextually appropriate error handling +- Subphases: each distinct catch pattern = one commit + +### Phase 4: Extractor decomposition +- Split large `walkXNode` switch cases into handler functions +- Keep dispatcher thin — handler per node kind +- Subphases: each extractor = one commit + +### Phase 5: General decomposition +- Read the gauntlet recommendation for the specific target +- Apply the recommended decomposition strategy +- Subphases: each function split = one commit + +### Phase 6: Small FAIL fixes +- Read the gauntlet recommendation for the specific target +- Apply the recommended fix (complexity reduction, metric improvement) +- Group by domain where possible + +--- + +## Step 2 — Per-target execution loop + +For each target in the current phase: + +1. **Skip if done.** Check if target is already in `execution.completedTargets`. If so, skip. + +2. **Update state.** Set `execution.currentTarget` in `titan-state.json`. + +3. **Read gauntlet entry.** Find this target in `gauntlet.ndjson` → get recommendation, violations, metrics. + +4. **Understand before touching.** Run codegraph commands: + ```bash + codegraph context -T --json + ``` + If blast radius > 0: + ```bash + codegraph fn-impact -T --json + ``` + +5. **Check if already fixed.** If the file has changed since gauntlet ran, re-check metrics: + ```bash + codegraph complexity --file --health -T --json + ``` + If the target now passes all thresholds, skip with note: "Target already passes — skipping." + +6. **Read source file(s).** Understand the code before editing. + +7. **Apply the change** based on phase strategy (Step 1) + gauntlet recommendation. + +8. **Run tests:** + ```bash + npm test 2>&1 + ``` + If tests fail → go to rollback (step 10). + +9. **Run /titan-gate:** + Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 10). + +10. **On success:** + ```bash + git add + git commit -m "" + ``` + - Record commit SHA in `execution.commits` + - Add target to `execution.completedTargets` + - Update `titan-state.json` + +11. **On failure (test or gate):** + ```bash + git checkout -- + ``` + - Add to `execution.failedTargets` with reason: `{ "target": "", "reason": "", "phase": N }` + - Clear `execution.currentTarget` + - **Continue to next target** — don't block the whole phase + +--- + +## Step 3 — Phase completion + +When all targets in the phase are processed: + +1. Add phase number to `execution.completedPhases` +2. Advance `execution.currentPhase` to the next phase number +3. Clear `execution.currentTarget` +4. Write updated `titan-state.json` + +--- + +## Step 4 — Report + +Print: + +``` +## Phase N Complete: