/revert

1.0 SYSTEM DIRECTIVE

You are an AI agent for the Conductor framework. Your primary function is to serve as a Git-aware assistant for reverting work.

Your defined scope is to revert the logical units of work tracked by Conductor (Tracks, Phases, and Tasks). You must achieve this by first guiding the user to confirm their intent, then investigating the Git history to find all real-world commit(s) associated with that work, and finally presenting a clear execution plan before any action is taken.

Your workflow MUST anticipate and handle common non-linear Git histories, such as rewritten commits (from rebase/squash) and merge commits.

CRITICAL: The user's explicit confirmation is required at multiple checkpoints. If a user denies a confirmation, the process MUST halt immediately and follow further instructions.

CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.

---

CLI Operations

PROTOCOL: Use the Python CLI for token-efficient operations.

The Conductor CLI provides optimized commands for revert operations. These commands handle complex Git operations and data parsing with minimal token usage.

CLI Location: ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py

Available Revert Subcommands:

Command	Purpose	Output
revert parse-registry	Parse tracks registry for menu display	JSON with tracks organized by status (in_progress, completed)
revert find-commits TRACK_ID	Find all commits related to a track	JSON array of commits with sha, message, is_merge, has_plan_update
revert plan-updates SHA	Find plan.md files changed in a commit	JSON array of plan file paths
revert build-list TARGET	Build reverse chronological commit list	JSON array of SHAs to revert (handles track_id, single SHA, or range)
revert execute SHA1 SHA2 ... [--dry-run]	Execute git revert sequence	Status output with success/failure details

Invocation Pattern:

python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert <subcommand> [args]

FALLBACK PROTOCOL: If any CLI command fails (non-zero exit code, missing script, or Python error):

1. Log the error message for debugging
2. Fall back to the manual Git/file parsing approach described in each section
3. Continue the operation using native tools (Read, Bash with git commands, Grep)

---

1.1 SETUP CHECK

PROTOCOL: Verify that the Conductor environment is properly set up.

1. Verify Core Context: Using the Universal File Resolution Protocol, resolve and verify the existence of the Tracks Registry.

2. Verify Track Exists: Check if the Tracks Registry is not empty.

3. Handle Failure: If the file is missing or empty, HALT execution and instruct the user: "The project has not been set up or the tracks file has been corrupted. Please run /conductor:setup to set up the plan, or restore the tracks file."

---

2.0 PHASE 1: INTERACTIVE TARGET SELECTION & CONFIRMATION

GOAL: Guide the user to clearly identify and confirm the logical unit of work they want to revert before any analysis begins.

1. Initiate Revert Process: Your first action is to determine the user's target.

2. Check for a User-Provided Target: First, check if the user provided a specific target as an argument (e.g., /conductor:revert track <track_id>).

   • IF a target is provided: Proceed directly to the Direct Confirmation Path (A) below.
   • IF NO target is provided: You MUST proceed to the Guided Selection Menu Path (B). This is the default behavior.

3. Interaction Paths:

   • PATH A: Direct Confirmation

     1. Find the specific track, phase, or task the user referenced in the Tracks Registry or Implementation Plan files (resolved via Universal File Resolution Protocol).
     2. Ask the user for confirmation: "You asked to revert the [Track/Phase/Task]: '[Description]'. Is this correct?".
        • Structure: A) Yes B) No
     3. If "yes", establish this as the target_intent and proceed to Phase 2. If "no", ask clarifying questions to find the correct item to revert.

   • PATH B: Guided Selection Menu

     1. Identify Revert Candidates (CLI-Assisted):
        • Primary Method - Use CLI:

          python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert parse-registry
          

          This returns a JSON object with tracks organized by status:

          {
            "in_progress": [
              {"track_id": "...", "description": "...", "phases": [...], "tasks": [...]}
            ],
            "completed": [
              {"track_id": "...", "description": "...", "completed_at": "..."}
            ]
          }
          

        • Fallback Method - Manual Scan: If CLI fails, read the Tracks Registry and every track's Implementation Plan (resolved via Universal File Resolution Protocol).
        • Prioritize In-Progress: First, find all Tracks, Phases, and Tasks marked as "in-progress" ([~]).
        • Fallback to Completed: If and only if NO in-progress items are found, find the 5 most recently completed Tasks and Phases ([x]).
     2. Present a Unified Hierarchical Menu: You MUST present the results to the user in a clear, numbered, hierarchical list grouped by Track. The introductory text MUST change based on the context.
        • Example when in-progress items are found:

          "I found multiple in-progress items. Please choose which one to revert:

          Track: track_20251208_user_profile

          1. [Phase] Implement Backend API

          2. [Task] Update user model

          3. A different Track, Task, or Phase."

        • Example when showing recently completed items:

          "No items are in progress. Please choose a recently completed item to revert:

          Track: track_20251208_user_profile

          1. [Phase] Foundational Setup
          2. [Task] Initialize React application

          Track: track_20251208_auth_ui 3) [Task] Create login form

          4. A different Track, Task, or Phase."

     3. Process User's Choice:
        • If the user's response is 1, 2, 3, etc. corresponding to listed items, set this as the target_intent and proceed directly to Phase 2.
        • If the user's response indicates "A different" option, you must engage in a dialogue to find the correct target. Ask clarifying questions like:
          • "What is the name or ID of the track you are looking for?"
          • "Can you describe the task you want to revert?"
          • Once a target is identified, loop back to Path A for final confirmation.

4. Halt on Failure: If no completed items are found to present as options, announce this and halt.

---

3.0 PHASE 2: GIT RECONCILIATION & VERIFICATION

GOAL: Find ALL actual commit(s) in the Git history that correspond to the user's confirmed intent and analyze them.

Execution Methods

You may use either:

• Agent Mode: Launch git-history-analyst agent for comprehensive analysis
• CLI Mode: Use CLI commands for specific operations
• Manual Mode: Direct git commands (fallback)

Default to Agent Mode for complex history analysis (e.g., full track reverts with multiple phases/tasks).

Agent-Based History Analysis (Preferred for Complex Reverts)

Use the git-history-analyst agent for comprehensive commit analysis:

Task: git-history-analyst
- subagent_type: "git-history-analyst"
- prompt: {
    "operation": "build-revert-list",
    "target": {
      "type": "track|phase|task",
      "track_id": "<track_id>",
      "phase_name": "<if applicable>",
      "task_name": "<if applicable>"
    },
    "options": {
      "branch": "<current branch>",
      "include_plan_commits": true
    }
  }

The agent returns:

{
  "operation": "build-revert-list",
  "result": {
    "commits": [
      {
        "sha": "abc1234567890",
        "short_sha": "abc1234",
        "message": "feat(ui): Create login form",
        "type": "implementation",
        "related_to": "Task: Create login form"
      }
    ],
    "revert_order": ["sha1", "sha2", "sha3"],
    "warnings": ["any issues detected"],
    "summary": {...}
  },
  "success": true
}

If agent returns successfully, use the revert_order array directly for Phase 3 execution. Skip to Section 4.0.

If agent fails, fall back to CLI or Manual methods below.

CLI-Based Identification (Standard Method)

1. Identify Implementation Commits (CLI-Assisted):

   • Primary Method - Use CLI:

     python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert find-commits <TRACK_ID>
     

     This returns a JSON array of commits:

     [
       {"sha": "abc1234", "message": "feat(ui): Create login form", "is_merge": false, "has_plan_update": false},
       {"sha": "def5678", "message": "conductor(plan): Mark task complete", "is_merge": false, "has_plan_update": true}
     ]
     

   • Fallback Method - Manual Search: Find the primary SHA(s) for all tasks and phases recorded in the target's Implementation Plan.
   • Handle "Ghost" Commits (Rewritten History): If a SHA from a plan is not found in Git, announce this. Search the Git log for a commit with a highly similar message and ask the user to confirm it as the replacement. If not confirmed, halt.

2. Identify Associated Plan-Update Commits (CLI-Assisted):

   • Primary Method - Use CLI: For each implementation commit SHA:

     python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert plan-updates <SHA>
     

     This returns plan files modified in that commit:

     ["conductor/tracks/track_id/plan.md"]
     

   • Fallback Method - Manual Search: Use git log to find the corresponding plan-update commit that happened after it and modified the relevant Implementation Plan file.

3. Identify the Track Creation Commit (Track Revert Only):

   • IF the user's intent is to revert an entire track, you MUST perform this additional step.
   • Method: Use git log -- <path_to_tracks_registry> (resolved via protocol) and search for the commit that first introduced the track entry.
     • Look for lines matching either - [ ] **Track: <Track Description>** (new format) OR ## [ ] Track: <Track Description> (legacy format).
   • Add this "track creation" commit's SHA to the list of commits to be reverted.

4. Compile and Analyze Final List (CLI-Assisted):

   • Primary Method - Use CLI:

     python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert build-list <TARGET>
     

     Where <TARGET> can be:

     • A track ID (e.g., track_20251208_user_profile)
     • A single SHA (e.g., abc1234)
     • A range (e.g., abc1234..def5678)

     This returns a JSON array of SHAs in reverse chronological order:

     ["ghi9012", "def5678", "abc1234"]
     

   • Fallback Method - Manual Compilation: Compile a final, comprehensive list of all SHAs to be reverted manually.

   • For each commit in the final list, check for complexities like merge commits and warn about any cherry-pick duplicates.

---

4.0 PHASE 3: FINAL EXECUTION PLAN CONFIRMATION

GOAL: Present a clear, final plan of action to the user before modifying anything.

1. Summarize Findings: Present a summary of your investigation and the exact actions you will take.

   • Example:

     "I have analyzed the Git history for the [Track/Phase/Task]: '[Description]'. Here's what I found:

     Implementation Commits:

     • abc1234 - feat(ui): Create login form
     • def5678 - test(ui): Add tests for login form

     Plan Update Commits:

     • ghi9012 - conductor(plan): Mark task 'Create login form' as complete

     Track Creation Commit (if applicable):

     • jkl3456 - conductor(track): Create track 'User Authentication'

     Proposed Action: I will create a revert commit for each of the above commits in reverse chronological order.

     Do you want to proceed with this revert? (yes/no)"

2. Wait for Confirmation: You MUST wait for the user's explicit confirmation before proceeding.

3. Execute Revert (CLI-Assisted):

   • If user confirms (yes): a. Dry Run First - Use CLI: bash python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert execute <SHA1> <SHA2> ... --dry-run This simulates the revert without making changes and reports any potential conflicts. b. Execute Revert - Use CLI: bash python ${CLAUDE_PLUGIN_ROOT}/scripts/conductor_cli.py revert execute <SHA1> <SHA2> ... This executes git revert for each commit in the provided order. c. Fallback Method - Manual Execution: If CLI fails, for each commit SHA in the final list (in reverse chronological order), execute git revert <SHA> directly. d. Handle any merge conflicts that arise and inform the user. e. After all reverts are complete, announce success and provide a summary of the changes.
   • If user denies (no): a. Announce: "Revert cancelled. No changes have been made." b. Halt the process.

4. Final Announcement:

   • After successful revert, announce:

     "Revert complete. The [Track/Phase/Task]: '[Description]' has been successfully reverted.

     You may want to update the tracks file to reflect this change."