docs: add /titan-forge skill (Titan Paradigm execution phase)#485
Conversation
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 finished @carlos-alm's task —— View job PR Review:
|
Greptile SummaryThis PR adds Key changes:
Issues found:
Confidence Score: 3/5
Important Files Changed
Sequence DiagramsequenceDiagram
actor User
participant FORGE as /titan-forge
participant State as titan-state.json
participant Gate as /titan-gate
participant Git as git
User->>FORGE: invoke (--phase N / --target / --dry-run / --yes)
FORGE->>Git: fetch + merge origin/main
FORGE->>State: read sync.json, titan-state.json, gauntlet artifacts
FORGE->>State: initialize execution block (if first run)
FORGE-->>User: print plan + confirm (unless --yes)
loop For each target in phase
FORGE->>State: set currentTarget
FORGE->>FORGE: codegraph context + fn-impact
FORGE->>FORGE: check if already fixed (complexity --health)
FORGE->>FORGE: apply code change (phase strategy)
FORGE->>Git: npm test
alt tests fail
FORGE->>Git: git checkout -- <files>
FORGE->>State: add to failedTargets, continue
else tests pass
FORGE->>Gate: invoke /titan-gate
alt gate FAIL (cycle)
Note over FORGE,Gate: Edge case says "stop immediately"<br/>but Step 9→11 says "continue" ⚠️
FORGE->>Git: git checkout -- <files>
FORGE->>State: add to failedTargets
else gate FAIL (other)
FORGE->>Git: git checkout -- <files>
FORGE->>State: add to failedTargets, continue
else gate PASS
FORGE->>Git: git add + git commit
FORGE->>State: record SHA, add to completedTargets
end
end
end
FORGE->>State: add phase to completedPhases, advance currentPhase
FORGE-->>User: Phase N complete report + next phase prompt
Last reviewed commit: 3edd802 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ``` | ||
| 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). |
There was a problem hiding this comment.
Both Step 8 and Step 9 direct the agent to "go to rollback (step 10)", but Step 10 is actually the success handler ("On success: git add … git commit …"). The rollback/failure logic is in Step 11 ("On failure (test or gate)"). An LLM executing this skill will read "step 10" literally and apply the success path instead of rolling back, silently committing a broken change.
| ``` | |
| 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). | |
| If tests fail → go to rollback (step 11). | |
| 9. **Run /titan-gate:** | |
| Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 11). |
There was a problem hiding this comment.
Fixed in 3edd802 — rollback step references corrected from step 10 to step 11 in both Step 8 and Step 9.
| **Arguments** (from `$ARGUMENTS`): | ||
| - No args → run next incomplete phase | ||
| - `--phase N` → jump to specific phase | ||
| - `--target <name>` → run single target only (for retrying failures) | ||
| - `--dry-run` → show what would be done without changing code |
There was a problem hiding this comment.
--yes flag undocumented
Step 0.8 reads: "Ask for confirmation before starting (unless $ARGUMENTS contains --yes)", but --yes does not appear in the argument-hint frontmatter or the Arguments list here. Users (and the LLM agent itself when constructing the invocation) cannot discover this flag from the skill's own help text.
| **Arguments** (from `$ARGUMENTS`): | |
| - No args → run next incomplete phase | |
| - `--phase N` → jump to specific phase | |
| - `--target <name>` → run single target only (for retrying failures) | |
| - `--dry-run` → show what would be done without changing code | |
| **Arguments** (from `$ARGUMENTS`): | |
| - No args → run next incomplete phase | |
| - `--phase N` → jump to specific phase | |
| - `--target <name>` → run single target only (for retrying failures) | |
| - `--dry-run` → show what would be done without changing code | |
| - `--yes` → skip confirmation prompt before starting |
The argument-hint in the frontmatter should also be updated:
argument-hint: <--phase N> <--target name> <--dry-run> <--yes>
There was a problem hiding this comment.
Fixed in 3edd802 — added --yes to the Arguments list and updated the argument-hint frontmatter.
| 5. **Initialize execution state** (if first run). Add to `titan-state.json`: | ||
| ```json | ||
| { | ||
| "execution": { | ||
| "currentPhase": 1, | ||
| "completedPhases": [], | ||
| "currentTarget": null, | ||
| "completedTargets": [], | ||
| "failedTargets": [], | ||
| "commits": [] | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The Rules section (line 227) states: "Subphase awareness — phases 3-6 have subphases. Each subphase = one commit. Track at subphase level." However, the execution state block initialized here has no subphase fields (currentSubphase, completedSubphases). If the agent is interrupted mid-subphase (e.g., during Phase 3 error-handling commits), re-running will restart the entire phase rather than picking up from the correct subphase, potentially re-applying already-committed changes.
Consider adding subphase tracking to the schema:
| 5. **Initialize execution state** (if first run). Add to `titan-state.json`: | |
| ```json | |
| { | |
| "execution": { | |
| "currentPhase": 1, | |
| "completedPhases": [], | |
| "currentTarget": null, | |
| "completedTargets": [], | |
| "failedTargets": [], | |
| "commits": [] | |
| } | |
| } | |
| ``` | |
| ```json | |
| { | |
| "execution": { | |
| "currentPhase": 1, | |
| "completedPhases": [], | |
| "currentTarget": null, | |
| "currentSubphase": null, | |
| "completedTargets": [], | |
| "completedSubphases": [], | |
| "failedTargets": [], | |
| "commits": [] | |
| } | |
| } |
There was a problem hiding this comment.
Fixed in 3edd802 — added currentSubphase and completedSubphases fields to the execution state schema.
carlos-alm
force-pushed
the
docs/titan-forge-skill
branch
from
ea74e4c to
3edd802
Compare
1 participant
Summary
/titan-forgeskill — the missing execution phase of the Titan Paradigm that readssync.jsonand makes the actual code changes/titan-gatedocs/examples/claude-code-skills/README.mdwith FORGE in pipeline diagram, skills table, usage examples, and command referenceTest plan
/titan-forgeis recognized as a skill by Claude Code/titan-forge --dry-runafter a/titan-syncto confirm plan parsing