conductor-worktree-hitl

# Conductor++ Asynchronous Git Worktree & GHI HITL Skill This skill guides the agent to execute parallel software development tasks using Git Worktrees, Conductor quality gates, and GitHub Issues (GHI) for Human-in-the-Loop (HITL) communication. ## Core Flow & Execution Steps ### 1. Worktree Isolation Setup Before performing any task modifications, create an isolated Git Worktree: 1. Verify that the main repository is clean (`git status`). 2. Add a new worktree check-out under `.worktrees/issue-<number>-<role>`: ```bash git worktree add .worktrees/issue-<number>-<role> -b feature/issue-<number> ``` 3. Navigate your context into the worktree directory. All subsequent tool runs (editing, compiling, testing) must happen within this worktree. 4. **Symlink the Conductor Folder & Shared Secrets**: Inside the worktree directory, create symbolic links pointing back to the main repository's `conductor/` directory and `.env` file (if present) to ensure shared configuration/secrets sync: ```bash ln -s ../../conductor conductor if [ -f ../../.env ]; then ln -s ../../.env .env; fi ``` This ensures a single point of sync/truth for all Conductor++ metadata and environment configurations. 5. **Configure Git Hygiene**: To prevent the subagent from accidentally tracking or staging the `conductor` symlink, track metadata, or `.env` files to its feature branch, add them to the worktree's local exclude file: ```bash echo "conductor" >> $(git rev-parse --git-dir)/info/exclude echo ".env" >> $(git rev-parse --git-dir)/info/exclude ``` 6. If conflicts arise, find a way to solve these conflicts deterministically. Eg, say different agents work on different worktrees and need to spin up a web server on port 8080, use this DEFAULT OVER CONFIGURATION instead: use port 42000 + GitHub Issue. 7. **Copy Conductor Scripts**: Copy the scripts in `scripts/` to the repository's `conductor/bin/` folder (create it if it doesn't exist). This should be done during setup or whenever the skill scripts are updated: ```bash mkdir -p conductor/bin # ./scripts/ is relative to this skill's directory (resolved automatically by Gemini CLI) cp ./scripts/* conductor/bin/ chmod +x conductor/bin/* ``` At startup, run a diff to make sure you use the latest version. ### 2. Conductor Quality Gates & Plan Roast 1. Verify the track's `metadata.json` configuration. Populate the `"worktree"`, `"github_issue"`, and `"agent"` blocks. You MUST explicitly set `"agent": "<AgentName>"` at the root level of `metadata.json` so that the conductor inspector knows exactly which agent is assigned to the track, avoiding incorrect inference from reused or generic worktree directory paths. 2. **Injecting GitHub Issues as Tasks**: If specific tasks inside the track are tracked in separate GitHub Issues, use the `inject-ghi` utility to import them into the track's `"tasks"` database: ```bash ./scripts/inject-ghi --issue <number> ``` 3. **Handling Task-Specific Issues**: - If a task has a `github_issue_url` specified, fetch the issue's contents and comments for context or human input before starting. - When the task is complete, post a confirmation comment on the issue page. 4. Before coding, execute the Conductor `/roastme` command to analyze the `plan.md` against product guidelines and code style rules. 5. If `/roastme` identifies unresolved design constraints, proceed to the communication protocol. ### 3. Asynchronous Multiple-Choice Choice (`ask_me`) If you require clarification on a design choice, UI asset, or logic condition: 1. **Format the Question**: Create a numbered multiple-choice list with clear context and a write-in option (option 4/other). 2. **Attach Screenshots (UI Tasks)**: - If the query is visual, capture a screenshot of the local preview or simulator. - Save the screenshot to the track's assets folder (e.g. `subtasks/TODAY/assets/`). - Reference the raw GitHub URL or path of the screenshot in the comment. 3. **Publish to GitHub**: Post the comment to the assigned GitHub Issue with the prefix `[QUESTION][<your-agent-role>]`. 4. **Local Memory Registry**: Append the question structure to the `"active_questions"` array in `metadata.json`: ```json "active_questions": [ { "question_id": "<unique_id>", "question": "<question_text>", "status": "awaiting_human", "answer": null } ] ``` *(For complete schema structure, see [references/question-awaiting.json](./references/question-awaiting.json) for the open question format, and [references/question-answered.json](./references/question-answered.json) for the answered question format).* 5. **Enter Polling Sleep**: Periodically read `metadata.json` (every 15 seconds). Once the local polling script updates the question status to `"answered"`, extract the `"answer"` value, clear the question from the local queue, and resume. ### 4. Verification & Local Commit (No Remote Pushing) 1. **The Real-Code Mandate (No Doc-Only PRs)**: When implementing a feature or bugfix track, you MUST produce tangible, meaningful changes to the actual executable codebase (e.g., application scripts, Python algorithms, React UI code). Under no circumstances should a feature track finish with only markdown docs or Conductor metadata changes—no "Jerry-work" allowed! 2. **Mandatory Test Expansion**: Every feature or bugfix track MUST introduce new automated unit tests or expand existing test suites (e.g., `tests/test_*.py`) proving that the new code is fully functional and regression-proof. 3. Implement the feature and verify all unit tests pass cleanly. 4. Run the linting suite and verify test coverage meets style requirements (>80%). 5. **Commit Locally (Do NOT Push)**: Stage and commit all code changes locally to your feature branch. Under no circumstances should you run `git push`. 6. Attach a detailed summary using Git Notes: ```bash git notes add -m "Task completed: <summary>" <commit-hash> ``` 7. Mark the task status as `completed` in `metadata.json`. The coordinator (Agostina) will handle checking out the branch, validation, merging, and final pushing. --- ## 📊 Conductor Track JSON (metadata.json) Evolution Every Conductor track maintains its state in a specific metadata file at a standard path: * **Sample Path**: `conductor/tracks/telegram_incident_creation/metadata.json` The file structure evolves dynamically as the track is assigned to agents, linked to GitHub Issues (GHI), and processes human feedback: ### 1. Initial State (Unassigned) When a track is first created, it starts with only basic details *(see reference file [references/track-initial.json](./references/track-initial.json))*: ```json { "track_id": "telegram_incident_creation", "status": "NEW", "description": "Implement incident creation in telegram", "tasks": [] } ``` ### 2. Assignment State (Agent & Worktree Setup) When a subagent checks out the track, it updates `metadata.json` to assign itself (`"agent"`) and document its isolated worktree branch and path *(see reference file [references/track-assigned.json](./references/track-assigned.json))*: ```json { "track_id": "telegram_incident_creation", "status": "ACTIVE", "description": "Implement incident creation in telegram", "agent": "Mario", "worktree": { "branch": "feature/issue-123", "directory": ".worktrees/issue-123-mario" }, "tasks": [] } ``` ### 3. Linked to GitHub Issue (GHI Integration) When associated with a GitHub Issue (GHI), a `"github_issue"` block is populated containing the issue number: ```json { "track_id": "telegram_incident_creation", "status": "ACTIVE", "description": "Implement incident creation in telegram", "agent": "Mario", "worktree": { "branch": "feature/issue-123", "directory": ".worktrees/issue-123-mario" }, "github_issue": { "number": 123 }, "tasks": [] } ``` ### 4. Awaiting Human Input (HITL Active) When the subagent posts a question to the GHI, it appends the question to `"active_questions"` with `"status": "awaiting_human"`: ```json { "track_id": "telegram_incident_creation", "status": "ACTIVE", "description": "Implement incident creation in telegram", "agent": "Mario", "worktree": { "branch": "feature/issue-123", "directory": ".worktrees/issue-123-mario" }, "github_issue": { "number": 123 }, "active_questions": [ { "agent": "Mario", "question": "Should we default to HTML formatting or MarkdownV2 for Telegram message payloads?", "status": "awaiting_human", "created_at": "2026-06-16T11:00:00Z" } ], "tasks": [] } ``` ### 5. Answered State (HITL Complete) Once the polling script parses the answer from the GHI comments, it updates the question block to `"status": "answered"`, adds the `"answer"`, and attaches the `"vehicle"` delivery details: ```json { "track_id": "telegram_incident_creation", "status": "ACTIVE", "description": "Implement incident creation in telegram", "agent": "Mario", "worktree": { "branch": "feature/issue-123", "directory": ".worktrees/issue-123-mario" }, "github_issue": { "number": 123 }, "active_questions": [ { "agent": "Mario", "question": "Should we default to HTML formatting or MarkdownV2 for Telegram message payloads?", "status": "answered", "answer": "HTML is preferred for simplicity and better parsing consistency in our Telegram library.", "vehicle": { "type": "telegram", "medium": "audio_message", "delivered_by": "human", "original_transcript": "Hey Mario, let's go with HTML formatting, it is much easier to maintain." }, "created_at": "2026-06-16T11:00:00Z" } ], "tasks": [], "updated_at": "2026-06-16T11:05:00Z" } ```