chore(skill): add codegraph install step to titan-run pre-flight

[carlos-alm]

Summary

• Adds a new pre-flight step (Step 4) in /titan-run that installs the latest @optave/codegraph globally before the pipeline begins
• Logs the installed version for traceability
• Gracefully continues with the existing version if install fails

Test plan

• Run /titan-run and verify it installs the latest codegraph before proceeding
• Verify pipeline continues if npm install -g fails (e.g., no network)

[greptile-apps]

Greptile Summary

This PR adds a single, narrowly scoped change to .claude/skills/titan-run/SKILL.md. The pre-flight section of the titan-run orchestrator skill now includes a new Step 4 that globally installs @optave/codegraph@latest before any sub-agent is dispatched. The installed version is logged via codegraph --version || true, where the || true guard ensures the orchestrator continues even if the binary is unexpectedly absent after a failed install. If the install itself fails, the skill warns the user but does not abort — sub-agents may still function if a project-local version of codegraph is available.

Key observations:

• The step is inserted at the right position: after argument parsing/state-resume (Step 3) and before the main-branch sync (Step 5), so codegraph is available before sub-agents open their context windows.
• The || true guard (added per prior feedback) correctly prevents a second cascading error when the binary is absent.
• The project-local fallback note (added per prior feedback) gives users a clear mental model of the failure path.
• Renumbering of former Steps 4 and 5 to Steps 5 and 6 is clean and complete.
• All P1 issues raised in previous review rounds have been addressed.

Confidence Score: 5/5

Safe to merge — all prior review concerns resolved, no remaining issues

Both P1 findings from previous review rounds have been addressed: codegraph --version || true prevents a cascading failure when the binary is absent, and the guidance text now explicitly mentions the project-local fallback path. The change is minimal, well-placed in the pre-flight flow, and does not affect any runtime code.

No files require special attention

Important Files Changed

Filename	Overview
.claude/skills/titan-run/SKILL.md	Adds pre-flight Step 4 to install latest @optave/codegraph globally and log version before sub-agents run; graceful fallback on install failure; renumbers former Steps 4–5 to 5–6

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    S1["Step 1: Worktree check\ngit worktree list"] --> S2
    S2["Step 2: Parse arguments\ntargetPath · startPhase · gauntletBatchSize"] --> S3
    S3["Step 3: Check existing state\nRead titan-state.json"] --> S4
    S4["Step 4 ✨ NEW: Install latest codegraph\nnpm install -g @optave/codegraph@latest"] --> CHK{Install OK?}
    CHK -- Yes --> LOG["codegraph --version\nLog version for traceability"]
    CHK -- No --> WARN["Warn user\ncontinue — project-local may still work"]
    LOG --> S5
    WARN --> S5
    S5["Step 5: Sync with main\ngit fetch origin main && git merge"] --> MC{Merge conflict?}
    MC -- Yes --> STOP(["STOP: Resolve conflicts\nre-run /titan-run"])
    MC -- No --> S6["Step 6: Print plan\nBegin pipeline"]

Loading

_{Reviews (3): Last reviewed commit: "Merge main into docs/claude-code-archite..." | Re-trigger Greptile}

[greptile-apps]

ADR path points to a non-existent directory

Phase 1 Step 4 now reads ADRs from generated/architecture/decisions/, but that directory does not exist. The only ADR in the repo is docs/architecture/decisions/001-dual-engine-architecture.md, which lives at the old path. Running /architect after this change will silently find no ADRs, causing the audit to skip the entire ADR compliance section.

The same stale path is also referenced in Phase 3 → F. ADR Compliance (line ~105), which evaluates compliance against generated/architecture/decisions/.

Either migrate the ADR to generated/architecture/decisions/ or revert the path to docs/architecture/decisions/.

Suggested change

	4. **Read all ADRs in `generated/architecture/decisions/`.** These are the project's settled architectural decisions. Read every file — they document rationale, trade-offs, alternatives considered, and trajectory. The audit must evaluate the codebase *against* these decisions: are they being followed? Are the stated trade-offs still accurate? Has anything changed that invalidates the rationale?
	4. **Read all ADRs in `docs/architecture/decisions/`.** These are

[carlos-alm]

Fixed. The merge conflict resolution (a62a5c1) reverted all three ADR path references back to docs/architecture/decisions/ — the Step 4 reference that was in conflict, plus two additional occurrences in Phase 3 F. ADR Compliance (line ~105) and the deliverable section (line ~174) that git auto-merged with the stale generated/ path. All references now point to the correct directory where the ADR actually lives.

[greptile-apps]

codegraph --version runs unconditionally after a potentially failed install

The instructions say "if the install fails, warn the user but continue with whichever version is currently available." However, codegraph --version is written as a separate unconditional command block. If npm install -g fails and no previous codegraph binary exists on PATH (e.g., a brand-new CI runner), the version-logging command will also error out with command not found, leaving the AI agent without clear guidance for a second consecutive failure.

Consider making the intent explicit:

Suggested change

	4. **Install latest codegraph** (once, before any sub-agent runs):
	```bash
	npm install -g @optave/codegraph@latest
	```
	Log the installed version:
	```bash
	codegraph --version
	```
	If the install fails, warn the user but continue with whichever version is currently available.
	4. **Install latest codegraph** (once, before any sub-agent runs):
	```bash
	npm install -g @optave/codegraph@latest

Log the installed version (skip if codegraph is not available):

codegraph --version || true

If the install fails or codegraph is not found, warn the user but continue — the sub-agents may still work if a project-local version is available.

[carlos-alm]

Fixed in c5a7760. Applied the suggested change: codegraph --version || true to prevent a second error when the binary is absent, and updated the guidance text to mention project-local fallback.

[carlos-alm]

@greptileai

[carlos-alm]

The remaining ADR path references on lines 105 and 174 of architect/SKILL.md were fixed in commit 14e3339. All three generated/architecture/decisions/ references now correctly point to docs/architecture/decisions/. The titan-run || true guard was already applied in c5a7760.

Regarding CI:

• Validate commits: Fails on pre-existing commit 428e606 (body line > 100 chars). Cannot fix without rebase/force-push, which is not permitted.
• Test failures: 4 integration tests (incremental-edge-parity, incremental-parity, scoped-rebuild) are unrelated to this PR -- the only file changed is .claude/skills/titan-run/SKILL.md. These appear to be pre-existing failures on main.

[carlos-alm]

@greptileai