@harness-engineering/cli 1.22.0 → 1.23.0

package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md

@@ -531,7 +531,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 4. **Clear scratchpad for this phase.** Call `clearScratchpad({ session: sessionSlug, phase: phaseName, projectPath: projectPath })` to delete ephemeral research files for the completed phase. This frees disk space and prevents stale scratchpad data from leaking into future phases.
 
-5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
+5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
 
 6. **Write session summary.** Update the session summary to reflect the completed phase:
 
@@ -671,7 +671,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 6. **Check if pruning is needed.** Call `countLearningEntries(projectPath)`. If the count exceeds 30, suggest: "Global learnings.md has {count} entries (threshold: 30). Run `harness learnings prune` to analyze patterns and archive old entries."
 
-7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
+7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
 
 8. **Write final session summary.** Update the session summary to reflect completion:
 

package/dist/agents/skills/claude-code/harness-brainstorming/SKILL.md

@@ -161,7 +161,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
    - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
    - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
-   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`.
+   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
    - If no roadmap exists, skip this step silently.
 
 7. **Write handoff and suggest transition.** After the human approves the spec:

package/dist/agents/skills/claude-code/harness-execution/SKILL.md

@@ -293,7 +293,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 
    This overwrites any previous summary for this session. The index.md is updated automatically.
 
-6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. If no roadmap exists, skip silently.
+6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." If no roadmap exists, skip silently.
 
 7. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record.
 

package/dist/agents/skills/claude-code/harness-roadmap/SKILL.md

@@ -92,7 +92,7 @@ Unmatched plans: N (flag for review)
    - One H2 section per milestone
    - One H3 section per feature with 5 fields: `Status`, `Spec`, `Summary`, `Blockers`, `Plan`
 
-2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format:
+2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 
    ```markdown
    ---
@@ -173,7 +173,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Add Feature to Roadmap
 
-1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back.
+1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. If the milestone is `[NEW]`: create the milestone section, then add the feature.
 3. Write to `docs/roadmap.md`.
 
@@ -276,7 +276,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Apply Changes
 
-1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back.
+1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. Update `last_synced` timestamp in frontmatter.
 3. Write to `docs/roadmap.md`.
 
@@ -378,7 +378,7 @@ Choice?
    ```
 
 2. Wait for confirmation before writing.
-3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable.
+3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable. If falling back to direct manipulation, warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 4. Update `last_manual_edit` timestamp in frontmatter (since this is a human-driven edit).
 5. Write to `docs/roadmap.md`.
 
@@ -592,4 +592,4 @@ These are hard stops. Violating any gate means the process has broken down.
 
 - **When no specs or plans are found during `--create`:** Suggest creating a minimal roadmap with just a Backlog milestone containing features described verbally by the human. Alternatively, suggest running `harness:brainstorming` first to generate specs that can then be discovered by `--create`.
 - **When the roadmap file is malformed and cannot be parsed:** Report the specific parse error with line numbers if available. Suggest manual inspection of `docs/roadmap.md` or recreation with `--create` (after backing up the existing file).
-- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations."
+- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations. External sync skipped — run `manage_roadmap sync` when MCP is restored to push changes to GitHub."

package/dist/agents/skills/claude-code/harness-roadmap-pilot/SKILL.md

@@ -82,21 +82,26 @@ Proceed with Feature A? (y/n/pick another)
 
 ### Phase 4: ASSIGN -- Execute Assignment and Transition
 
-1. Call `assignFeature(roadmap, feature, currentUser, todayDate)` from `@harness-engineering/core`.
-   - This updates the feature's `Assignee` field
-   - Appends `assigned` record to assignment history (and `unassigned` for previous assignee if reassignment)
+1. Call `manage_roadmap` with action `update` to assign the feature:
 
-2. Serialize and write the updated roadmap to `docs/roadmap.md`.
+   ```json
+   manage_roadmap({
+     path: "<project-root>",
+     action: "update",
+     feature: "<feature-name>",
+     assignee: "<currentUser>"
+   })
+   ```
 
-3. If tracker config exists in `harness.config.json`, sync the assignment:
-   - Call the external tracker's `assignTicket` to push the assignment
-   - Log result but do not block on failure
+   - This updates the feature's `Assignee` field with assignment history tracking
+   - Automatically triggers external sync (GitHub Issues) if tracker config exists in `harness.config.json`
+   - External sync is fire-and-forget — errors are logged but do not block the assignment
 
-4. Determine the transition target:
+2. Determine the transition target:
    - If the feature has a `spec` field (non-null): transition to `harness:autopilot`
    - If the feature has no `spec`: transition to `harness:brainstorming`
 
-5. Present the transition to the human via `emit_interaction`:
+3. Present the transition to the human via `emit_interaction`:
 
    ```json
    emit_interaction({
@@ -122,7 +127,7 @@ Proceed with Feature A? (y/n/pick another)
    })
    ```
 
-6. Run `harness validate`.
+4. Run `harness validate`.
 
 ---
 
@@ -130,10 +135,9 @@ Proceed with Feature A? (y/n/pick another)
 
 - **`parseRoadmap` / `serializeRoadmap`** -- Parse and write `docs/roadmap.md`. Import from `@harness-engineering/core`.
 - **`scoreRoadmapCandidates`** -- Core scoring algorithm. Import from `@harness-engineering/core`. Takes a `Roadmap` and optional `PilotScoringOptions` (currentUser for affinity).
-- **`assignFeature`** -- Assignment with history tracking. Import from `@harness-engineering/core`. Handles new assignment and reassignment (unassigned + assigned records).
+- **`manage_roadmap update`** -- Used for assignment. Supports `assignee` field which delegates to `assignFeature` internally, handles history tracking, and automatically triggers external sync (GitHub Issues).
 - **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists).
 - **`harness validate`** -- Run after assignment is written.
-- **External sync** -- If `harness.config.json` has tracker config, use `fullSync` or direct `assignTicket` to push assignment to external service.
 
 ## Success Criteria
 
@@ -183,10 +187,10 @@ Human confirms **y**.
 **Phase 4: ASSIGN**
 
 ```
-Assigned: Graph Connector -> @cwarner
+manage_roadmap update: Graph Connector assignee -> @cwarner
 History: +1 record (assigned, 2026-04-02)
 Roadmap updated: docs/roadmap.md
-External sync: github:harness-eng/harness#43 assigned
+External sync: github:harness-eng/harness#43 assigned (automatic)
 
 Transitioning to harness:autopilot (spec exists)...
 ```

package/dist/agents/skills/codex/harness-autopilot/SKILL.md

@@ -531,7 +531,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 4. **Clear scratchpad for this phase.** Call `clearScratchpad({ session: sessionSlug, phase: phaseName, projectPath: projectPath })` to delete ephemeral research files for the completed phase. This frees disk space and prevents stale scratchpad data from leaking into future phases.
 
-5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
+5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
 
 6. **Write session summary.** Update the session summary to reflect the completed phase:
 
@@ -671,7 +671,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 6. **Check if pruning is needed.** Call `countLearningEntries(projectPath)`. If the count exceeds 30, suggest: "Global learnings.md has {count} entries (threshold: 30). Run `harness learnings prune` to analyze patterns and archive old entries."
 
-7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
+7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
 
 8. **Write final session summary.** Update the session summary to reflect completion:
 

package/dist/agents/skills/codex/harness-brainstorming/SKILL.md

@@ -161,7 +161,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
    - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
    - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
-   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`.
+   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
    - If no roadmap exists, skip this step silently.
 
 7. **Write handoff and suggest transition.** After the human approves the spec:

package/dist/agents/skills/codex/harness-execution/SKILL.md

@@ -293,7 +293,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 
    This overwrites any previous summary for this session. The index.md is updated automatically.
 
-6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. If no roadmap exists, skip silently.
+6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." If no roadmap exists, skip silently.
 
 7. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record.
 

package/dist/agents/skills/codex/harness-roadmap/SKILL.md

@@ -92,7 +92,7 @@ Unmatched plans: N (flag for review)
    - One H2 section per milestone
    - One H3 section per feature with 5 fields: `Status`, `Spec`, `Summary`, `Blockers`, `Plan`
 
-2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format:
+2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 
    ```markdown
    ---
@@ -173,7 +173,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Add Feature to Roadmap
 
-1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back.
+1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. If the milestone is `[NEW]`: create the milestone section, then add the feature.
 3. Write to `docs/roadmap.md`.
 
@@ -276,7 +276,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Apply Changes
 
-1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back.
+1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. Update `last_synced` timestamp in frontmatter.
 3. Write to `docs/roadmap.md`.
 
@@ -378,7 +378,7 @@ Choice?
    ```
 
 2. Wait for confirmation before writing.
-3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable.
+3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable. If falling back to direct manipulation, warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 4. Update `last_manual_edit` timestamp in frontmatter (since this is a human-driven edit).
 5. Write to `docs/roadmap.md`.
 
@@ -592,4 +592,4 @@ These are hard stops. Violating any gate means the process has broken down.
 
 - **When no specs or plans are found during `--create`:** Suggest creating a minimal roadmap with just a Backlog milestone containing features described verbally by the human. Alternatively, suggest running `harness:brainstorming` first to generate specs that can then be discovered by `--create`.
 - **When the roadmap file is malformed and cannot be parsed:** Report the specific parse error with line numbers if available. Suggest manual inspection of `docs/roadmap.md` or recreation with `--create` (after backing up the existing file).
-- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations."
+- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations. External sync skipped — run `manage_roadmap sync` when MCP is restored to push changes to GitHub."

package/dist/agents/skills/codex/harness-roadmap-pilot/SKILL.md

@@ -82,21 +82,26 @@ Proceed with Feature A? (y/n/pick another)
 
 ### Phase 4: ASSIGN -- Execute Assignment and Transition
 
-1. Call `assignFeature(roadmap, feature, currentUser, todayDate)` from `@harness-engineering/core`.
-   - This updates the feature's `Assignee` field
-   - Appends `assigned` record to assignment history (and `unassigned` for previous assignee if reassignment)
+1. Call `manage_roadmap` with action `update` to assign the feature:
 
-2. Serialize and write the updated roadmap to `docs/roadmap.md`.
+   ```json
+   manage_roadmap({
+     path: "<project-root>",
+     action: "update",
+     feature: "<feature-name>",
+     assignee: "<currentUser>"
+   })
+   ```
 
-3. If tracker config exists in `harness.config.json`, sync the assignment:
-   - Call the external tracker's `assignTicket` to push the assignment
-   - Log result but do not block on failure
+   - This updates the feature's `Assignee` field with assignment history tracking
+   - Automatically triggers external sync (GitHub Issues) if tracker config exists in `harness.config.json`
+   - External sync is fire-and-forget — errors are logged but do not block the assignment
 
-4. Determine the transition target:
+2. Determine the transition target:
    - If the feature has a `spec` field (non-null): transition to `harness:autopilot`
    - If the feature has no `spec`: transition to `harness:brainstorming`
 
-5. Present the transition to the human via `emit_interaction`:
+3. Present the transition to the human via `emit_interaction`:
 
    ```json
    emit_interaction({
@@ -122,7 +127,7 @@ Proceed with Feature A? (y/n/pick another)
    })
    ```
 
-6. Run `harness validate`.
+4. Run `harness validate`.
 
 ---
 
@@ -130,10 +135,9 @@ Proceed with Feature A? (y/n/pick another)
 
 - **`parseRoadmap` / `serializeRoadmap`** -- Parse and write `docs/roadmap.md`. Import from `@harness-engineering/core`.
 - **`scoreRoadmapCandidates`** -- Core scoring algorithm. Import from `@harness-engineering/core`. Takes a `Roadmap` and optional `PilotScoringOptions` (currentUser for affinity).
-- **`assignFeature`** -- Assignment with history tracking. Import from `@harness-engineering/core`. Handles new assignment and reassignment (unassigned + assigned records).
+- **`manage_roadmap update`** -- Used for assignment. Supports `assignee` field which delegates to `assignFeature` internally, handles history tracking, and automatically triggers external sync (GitHub Issues).
 - **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists).
 - **`harness validate`** -- Run after assignment is written.
-- **External sync** -- If `harness.config.json` has tracker config, use `fullSync` or direct `assignTicket` to push assignment to external service.
 
 ## Success Criteria
 
@@ -183,10 +187,10 @@ Human confirms **y**.
 **Phase 4: ASSIGN**
 
 ```
-Assigned: Graph Connector -> @cwarner
+manage_roadmap update: Graph Connector assignee -> @cwarner
 History: +1 record (assigned, 2026-04-02)
 Roadmap updated: docs/roadmap.md
-External sync: github:harness-eng/harness#43 assigned
+External sync: github:harness-eng/harness#43 assigned (automatic)
 
 Transitioning to harness:autopilot (spec exists)...
 ```

package/dist/agents/skills/cursor/harness-autopilot/SKILL.md

@@ -531,7 +531,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 4. **Clear scratchpad for this phase.** Call `clearScratchpad({ session: sessionSlug, phase: phaseName, projectPath: projectPath })` to delete ephemeral research files for the completed phase. This frees disk space and prevents stale scratchpad data from leaking into future phases.
 
-5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
+5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
 
 6. **Write session summary.** Update the session summary to reflect the completed phase:
 
@@ -671,7 +671,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 6. **Check if pruning is needed.** Call `countLearningEntries(projectPath)`. If the count exceeds 30, suggest: "Global learnings.md has {count} entries (threshold: 30). Run `harness learnings prune` to analyze patterns and archive old entries."
 
-7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
+7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
 
 8. **Write final session summary.** Update the session summary to reflect completion:
 

package/dist/agents/skills/cursor/harness-brainstorming/SKILL.md

@@ -161,7 +161,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
    - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
    - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
-   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`.
+   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
    - If no roadmap exists, skip this step silently.
 
 7. **Write handoff and suggest transition.** After the human approves the spec:

package/dist/agents/skills/cursor/harness-execution/SKILL.md

@@ -293,7 +293,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 
    This overwrites any previous summary for this session. The index.md is updated automatically.
 
-6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. If no roadmap exists, skip silently.
+6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." If no roadmap exists, skip silently.
 
 7. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record.
 

package/dist/agents/skills/cursor/harness-roadmap/SKILL.md

@@ -92,7 +92,7 @@ Unmatched plans: N (flag for review)
    - One H2 section per milestone
    - One H3 section per feature with 5 fields: `Status`, `Spec`, `Summary`, `Blockers`, `Plan`
 
-2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format:
+2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 
    ```markdown
    ---
@@ -173,7 +173,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Add Feature to Roadmap
 
-1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back.
+1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. If the milestone is `[NEW]`: create the milestone section, then add the feature.
 3. Write to `docs/roadmap.md`.
 
@@ -276,7 +276,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Apply Changes
 
-1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back.
+1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. Update `last_synced` timestamp in frontmatter.
 3. Write to `docs/roadmap.md`.
 
@@ -378,7 +378,7 @@ Choice?
    ```
 
 2. Wait for confirmation before writing.
-3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable.
+3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable. If falling back to direct manipulation, warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 4. Update `last_manual_edit` timestamp in frontmatter (since this is a human-driven edit).
 5. Write to `docs/roadmap.md`.
 
@@ -592,4 +592,4 @@ These are hard stops. Violating any gate means the process has broken down.
 
 - **When no specs or plans are found during `--create`:** Suggest creating a minimal roadmap with just a Backlog milestone containing features described verbally by the human. Alternatively, suggest running `harness:brainstorming` first to generate specs that can then be discovered by `--create`.
 - **When the roadmap file is malformed and cannot be parsed:** Report the specific parse error with line numbers if available. Suggest manual inspection of `docs/roadmap.md` or recreation with `--create` (after backing up the existing file).
-- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations."
+- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations. External sync skipped — run `manage_roadmap sync` when MCP is restored to push changes to GitHub."

package/dist/agents/skills/cursor/harness-roadmap-pilot/SKILL.md

@@ -82,21 +82,26 @@ Proceed with Feature A? (y/n/pick another)
 
 ### Phase 4: ASSIGN -- Execute Assignment and Transition
 
-1. Call `assignFeature(roadmap, feature, currentUser, todayDate)` from `@harness-engineering/core`.
-   - This updates the feature's `Assignee` field
-   - Appends `assigned` record to assignment history (and `unassigned` for previous assignee if reassignment)
+1. Call `manage_roadmap` with action `update` to assign the feature:
 
-2. Serialize and write the updated roadmap to `docs/roadmap.md`.
+   ```json
+   manage_roadmap({
+     path: "<project-root>",
+     action: "update",
+     feature: "<feature-name>",
+     assignee: "<currentUser>"
+   })
+   ```
 
-3. If tracker config exists in `harness.config.json`, sync the assignment:
-   - Call the external tracker's `assignTicket` to push the assignment
-   - Log result but do not block on failure
+   - This updates the feature's `Assignee` field with assignment history tracking
+   - Automatically triggers external sync (GitHub Issues) if tracker config exists in `harness.config.json`
+   - External sync is fire-and-forget — errors are logged but do not block the assignment
 
-4. Determine the transition target:
+2. Determine the transition target:
    - If the feature has a `spec` field (non-null): transition to `harness:autopilot`
    - If the feature has no `spec`: transition to `harness:brainstorming`
 
-5. Present the transition to the human via `emit_interaction`:
+3. Present the transition to the human via `emit_interaction`:
 
    ```json
    emit_interaction({
@@ -122,7 +127,7 @@ Proceed with Feature A? (y/n/pick another)
    })
    ```
 
-6. Run `harness validate`.
+4. Run `harness validate`.
 
 ---
 
@@ -130,10 +135,9 @@ Proceed with Feature A? (y/n/pick another)
 
 - **`parseRoadmap` / `serializeRoadmap`** -- Parse and write `docs/roadmap.md`. Import from `@harness-engineering/core`.
 - **`scoreRoadmapCandidates`** -- Core scoring algorithm. Import from `@harness-engineering/core`. Takes a `Roadmap` and optional `PilotScoringOptions` (currentUser for affinity).
-- **`assignFeature`** -- Assignment with history tracking. Import from `@harness-engineering/core`. Handles new assignment and reassignment (unassigned + assigned records).
+- **`manage_roadmap update`** -- Used for assignment. Supports `assignee` field which delegates to `assignFeature` internally, handles history tracking, and automatically triggers external sync (GitHub Issues).
 - **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists).
 - **`harness validate`** -- Run after assignment is written.
-- **External sync** -- If `harness.config.json` has tracker config, use `fullSync` or direct `assignTicket` to push assignment to external service.
 
 ## Success Criteria
 
@@ -183,10 +187,10 @@ Human confirms **y**.
 **Phase 4: ASSIGN**
 
 ```
-Assigned: Graph Connector -> @cwarner
+manage_roadmap update: Graph Connector assignee -> @cwarner
 History: +1 record (assigned, 2026-04-02)
 Roadmap updated: docs/roadmap.md
-External sync: github:harness-eng/harness#43 assigned
+External sync: github:harness-eng/harness#43 assigned (automatic)
 
 Transitioning to harness:autopilot (spec exists)...
 ```

package/dist/agents/skills/gemini-cli/harness-autopilot/SKILL.md

@@ -531,7 +531,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 4. **Clear scratchpad for this phase.** Call `clearScratchpad({ session: sessionSlug, phase: phaseName, projectPath: projectPath })` to delete ephemeral research files for the completed phase. This frees disk space and prevents stale scratchpad data from leaking into future phases.
 
-5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
+5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
 
 6. **Write session summary.** Update the session summary to reflect the completed phase:
 
@@ -671,7 +671,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 6. **Check if pruning is needed.** Call `countLearningEntries(projectPath)`. If the count exceeds 30, suggest: "Global learnings.md has {count} entries (threshold: 30). Run `harness learnings prune` to analyze patterns and archive old entries."
 
-7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
+7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
 
 8. **Write final session summary.** Update the session summary to reflect completion:
 

package/dist/agents/skills/gemini-cli/harness-brainstorming/SKILL.md

@@ -161,7 +161,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
    - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
    - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
-   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`.
+   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
    - If no roadmap exists, skip this step silently.
 
 7. **Write handoff and suggest transition.** After the human approves the spec:

package/dist/agents/skills/gemini-cli/harness-execution/SKILL.md

@@ -293,7 +293,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 
    This overwrites any previous summary for this session. The index.md is updated automatically.
 
-6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. If no roadmap exists, skip silently.
+6. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." If no roadmap exists, skip silently.
 
 7. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record.
 

package/dist/agents/skills/gemini-cli/harness-roadmap/SKILL.md

@@ -92,7 +92,7 @@ Unmatched plans: N (flag for review)
    - One H2 section per milestone
    - One H3 section per feature with 5 fields: `Status`, `Spec`, `Summary`, `Blockers`, `Plan`
 
-2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format:
+2. Write via `manage_roadmap` MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 
    ```markdown
    ---
@@ -173,7 +173,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Add Feature to Roadmap
 
-1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back.
+1. Add via `manage_roadmap add` MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. If the milestone is `[NEW]`: create the milestone section, then add the feature.
 3. Write to `docs/roadmap.md`.
 
@@ -276,7 +276,7 @@ Wait for confirmation before proceeding.
 
 #### Phase 3: WRITE -- Apply Changes
 
-1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back.
+1. Apply via `manage_roadmap sync` MCP tool if available, or via `manage_roadmap update` for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 2. Update `last_synced` timestamp in frontmatter.
 3. Write to `docs/roadmap.md`.
 
@@ -378,7 +378,7 @@ Choice?
    ```
 
 2. Wait for confirmation before writing.
-3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable.
+3. Apply all changes via `manage_roadmap update` / `manage_roadmap remove` MCP tool calls, or direct file manipulation if MCP is unavailable. If falling back to direct manipulation, warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
 4. Update `last_manual_edit` timestamp in frontmatter (since this is a human-driven edit).
 5. Write to `docs/roadmap.md`.
 
@@ -592,4 +592,4 @@ These are hard stops. Violating any gate means the process has broken down.
 
 - **When no specs or plans are found during `--create`:** Suggest creating a minimal roadmap with just a Backlog milestone containing features described verbally by the human. Alternatively, suggest running `harness:brainstorming` first to generate specs that can then be discovered by `--create`.
 - **When the roadmap file is malformed and cannot be parsed:** Report the specific parse error with line numbers if available. Suggest manual inspection of `docs/roadmap.md` or recreation with `--create` (after backing up the existing file).
-- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations."
+- **When MCP tool is unavailable:** Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core `parseRoadmap`/`serializeRoadmap` functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations. External sync skipped — run `manage_roadmap sync` when MCP is restored to push changes to GitHub."