project-resolver

---
name: project-resolver
description: Use Project Resolver to plan, execute, coordinate, verify, or continue governed project work using the authoritative repository, existing tools, roles, and reusable skills. Also use when working with a user's local computer, filesystem, terminal, or desktop, including Desktop Commander. Especially useful for multi-step Software flows and GitHub PR delivery.
---

# Project Resolver — portable entry

## Purpose
Enter the existing Resolver workflow for the user's actual task.

## Goal
Coordinate authorized work with current project and local-device instructions when relevant.

## When to use
For planning, executing, verifying or continuing governed project work.

## Inputs
Current task, applicable authority, selected project/ref and actual destination capabilities; local profile only when a user's computer is selected.

## Execution contract
Remote mode uses the available authorized provider and does not require a local device. A local-only task uses this packaged procedure, a real selected device, and an actually available permitted path to read its profile and any configured instruction source before substantive shell actions or project writes; it does not require GitHub, network access or the unpackaged kernel skill. Prefer direct reads; use a minimal read-only shell bootstrap only when a required direct bootstrap step is unsupported by the surface, including genuinely unresolved home, and applicable Owner/host rules allow it. Once the path is known, use direct reads when available. Never use shell to bypass a denial; if rules forbid shell before reading, do not launch it. Profile lookup, a directory choice and prose do not prove OS-level isolation. If a required local reference or capability is unavailable, report the precise limitation and continue independently executable remote work.

## Required outputs
Actual result and applicable durable references; for local work the profile/rules read or exact limitation.

## Procedure

Project Resolver augments the model's native reasoning. It does not replace judgment, create Owner authority or require every conversation to become an Engine task.

## Entry and authority

- Start from the user's actual outcome, existing approved decisions and current project authority. For GitHub-backed Software, the **remote** repository, Issue/PR/HEAD and available remote CI/Preview evidence are the development state. Avoid unrelated local-worktree scans, hidden local backlog and Desktop Commander for ordinary GitHub operations.
- Canonical Resolver: `https://github.com/TMCP-HUB/project-resolver`. For a GitHub-backed task or another actual need for canonical source, use a verified accessible ref and read its root `AGENTS.md`, `SYSTEM_MANIFEST.yaml` and `ROUTER.md`, then only the relevant role, workflow and skills. An authorized local-only task can use this packaged procedure without repository access; preserve applicable Owner, host and project instructions and do not claim an unread source was read. If the actual task requires repository evidence, its absence still limits that claim. Do not copy the Resolver into a target repo or invent parallel contracts.
- Determine the actual host, role and required capabilities from real context. Liaison can discuss and frame an Owner outcome; an admitted Director coordinates and may review a separate Executor's exact result; an independently selected Verifier checks its assigned claims. Never use role labels to bypass authority or infer that an installed plugin provides all these external actions.

For applicable product planning, use capabilities before interfaces: MCP may precede UI; agent-enabled products implement A2A where applicable, and discoverable public information supports AI search and semantic HTML. Apply these to the actual product scope, not unrelated bounded repairs, and do not invent deployment evidence or a network requirement for local-only work.

## Evidence-backed limits and complete deletion

Treat claimed product, provider and runtime limits as facts only when supported by applicable Owner decisions, contracts, relevant official documentation or direct observation. Keep unresolved assumptions explicit; an implementation default is a design choice, not an invented provider rule. Existing code or tests alone do not prove continued authority or necessity. Preserve actual approved requirements and protected security/data boundaries.

For an authorized removal or replacement, remove in-scope checks, scripts, configuration and CI steps whose sole purpose is the retired element, including absence-only checks. If a one-off absence check is used, remove it immediately after its first successful result before handoff. Keep checks of current behavior and active requirements. Do not add speculative restrictions, new tests or Owner gates.

## Mutable working assets

Ordinary working assets, including binary and static files, are mutable by default. Replacing, compressing, resizing, or optimizing them uses the existing file/storage and deploy workflow; a required stable URL does not require identical bytes. Archive/import checksums validate an exact historical copy, not future product content. Do not turn them into production-build blockers, mandatory external ZIPs, permanent asset manifests, or new approvals for routine edits. Enforce immutability, signing, or code/data pinning only for a specifically applicable security, evidence, release, or compatibility contract. Preserve real protections without adding speculative gates, tests, or registries.

## Causal stops and phase changes

After two successive mutating corrections on the same unresolved candidate or repair boundary each have been followed by an actually executed required check or observation that fails, **pause speculative edits on that boundary and enter causal audit immediately**, even when failure classes differ. Examine the whole relevant check/acceptance contract, all failures and prior corrections, identify the shared cause or distinct problems, then **resume the approved work with one bounded, evidence-led correction**. Do not abandon the whole project, use another blind patch, or request a new Owner decision without new material circumstances. An initial failure or an unavailable, unexecuted or unknown check is not a failed correction. A new chat, session, branch or HEAD does not reset that unresolved boundary. Preserve the candidate, failed-generation history and next action in the existing work record or available local handoff; continue independent authorized work. Two identical failures of one tool operation without new evidence stop that operation, not unrelated work.

When a material phase ends and its next foundation or direction is visible, compare only the affected in-scope path with the approved outcome and protected invariants. Determine which actual behavior needs each helper, compatibility bridge or duplicate layer; green CI or code age does not establish necessity. Keep what is needed, and simplify or remove obsolete pieces only within already authorized scope, preserving protected data and behavior. Do not introduce a recurring audit, blanket stop, new tests, manual acceptance or Owner gate.

When an actually available and selected structured Resolver path is used, carry the already made Director decision, identified boundary and current state through its existing inputs. This packaged procedure does not itself invoke that path, read GitHub, discover omitted decisions or enforce the caller's conduct; local-only work needs no network.

## Conditional local-computer entry
Before substantive shell actions or project writes on a user's computer, resolve the existing user/device workspace profile and read any configured local instruction source and applicable host/user rules. Prefer a direct file/host surface. If a required direct bootstrap step is unsupported by that surface and applicable Owner/host rules allow, use an actually available selected shell only for minimal read-only home/profile/rule lookup. This includes when the provider cannot resolve the home alias and no absolute home is known; a missing profile or access denial alone does not prove that. Once home is known, use direct profile/rule reads when available. Never bypass a file-access denial with shell, and obey a user's requirement to read rules before any shell. Reuse an exact Assignment/user-settings reference when present; otherwise use the selected device's per-user `~/.config/project-resolver/local-workspace.json` only where the provider can resolve home, including by permitted minimal bootstrap, or a known absolute home is available. Never infer a home path from examples or use shell when applicable rules must be read before any shell. If no usable profile exists, collect only missing choices: repository, agent instructions/tools and non-repository project areas, with an optional common parent, existing rule-file reference and preferred shell. Preserve already selected locations even outside the parent. Save a small per-user/device JSON profile at that locator by direct file operation when supported. If the surface lacks direct writing, a permitted selected shell may write only that profile after applicable rules are read; do not bypass a denial. Use a profile with exact keys `repository_root`, `agent_root`, `project_root`, and `instruction_file` when supplied; `common_parent` and `preferred_shell` are optional. Path values are absolute device paths; never store credentials or publish personal paths to a repository. Reuse an existing compatible host profile. If home resolution, reference access or persistence is unavailable, state the exact limit and request only the missing absolute reference; do not use shell contrary to applicable policy or claim later auto-loading. Carry the reference and applicable constraints to the actual local actor, which reads them before its local action. For a governed task that actually requires and can access the canonical source, `kernel/skills/local-workspace-operation/SKILL.md` is the fuller shared procedure; this packaged procedure suffices for local-only work. Never require local setup for remote-only work.

Reuse an existing authorized checkout and put a new clone, worktree, snapshot or source export only in the selected repository area unless the user explicitly authorized another destination. Use the chosen non-repository and agent-tool areas for their actual purposes; honor stronger applicable user/project rules and do not move or delete pre-existing user data. Set the actual task working directory for each terminal invocation, honor the user's shell, and reuse installed common per-user tools. Necessary app/user configuration, caches and logs remain distinct from project copies. Desktop Commander `allowedDirectories` affects direct file operations but not shell commands; an empty list allows all filesystem locations reachable by the process. If an allowlist is actually configured, preserve access to the profile, applicable rule file and other authorized destinations. Do not claim a sandbox from this setting or a `cd` command.

## Approved Workflow Director entry

An explicitly requested approved Workflow Director assignment enters the existing Control Director at its supplied frontier, not fresh Liaison. Reuse supplied Owner/Canon decisions, scope and durable refs, refresh only necessary current state, and begin the next admitted action. Apply actual host admission and existing capability, compilation, route and verification boundaries.

If the user designates a current-message pasted or attached task for execution, inspect visible attachment context and read the actual text using available file access, independent of its automatic filename, title, locale or extension. Select the designated workflow when several files exist; report a real ambiguity or exact access gap after checking available file access. Do not assert an unread file was read or infer execution from unrelated files without user instruction.

The Owner-facing / LSO Director provides a complete workflow brief and the fixed short launcher as two separate copyable units for each handoff to a separate Workflow Director, per `protocols/skills/session-handoff/SKILL.md`; both are sent in the same message. Workflow Director returns via the existing HANDOFF and current chat, or the existing Issue/PR for GitHub-backed work, if direct upstream contact is unavailable. Never automatically find or wake the strategic chat, or promise unattended background work.

## Native transport integrity

For an Owner-approved Work-hosted GitHub implementation, the Director may select a **distinct native Work Subagent** or Codex Cloud Executor with actual publishing capability. Neither Work Subagents nor Codex are a mandatory single-provider choice; retain a specifically frozen in-flight route. Retired Linear `@codex`, PR-comment coding commands and disconnected legacy Codex are not automatic substitutes. If the Owner chose a visible Desktop-integrated MCP browser, keep that visible interface rather than hidden Chrome or a different cloud browser. Report the exact unavailable capability; follow current Resolver root rules over archived provider guidance.

## GitHub without a mandatory local CLI

For GitHub Issue/PR/CI operations use the connected GitHub Connector/API already working in the session. A failed local `gh` executable is a tool-method failure, not loss of GitHub access or permission to stop the entire Work flow. Use another admitted method for the **same** GitHub operation without changing the selected physical Executor/transport or asking for approval again. A missing `gh` does not justify tool installation, legacy Codex/Linear dispatch, or hidden-browser workarounds. Only a genuinely unavailable mandatory operation may block its dependent step.

## First launch, reuse and recovery

A newly approved Software workstream has no previous Executor by default. **Do not search for a reusable worker before its first launch.** Use the already selected, demonstrated native launch facility to instantiate a new admitted Executor and bind its resulting task identity; creating an agent task is not creating a new execution environment or infrastructure. Do not repeat unchanged provider setup tests, ask Owner to choose a worker, or treat "none found" as a terminal result.

For subsequent assignments, reuse a **known active** compatible agent when useful, otherwise create a newly admitted Work Subagent, Codex worker or other approved Executor through the selected configured route. If an earlier launch may still be running or its acknowledgement is unknown, reconcile that specific task/session and its available result or handoff once before any replacement. For GitHub-backed work also reconcile the applicable exact Issue/PR/HEAD; absence of a GitHub commit alone does not prove the old task never started. A confirmed terminal/lost task with no recoverable unpublished work may be replaced without a new Issue, PR, transport or Owner decision.

Optional child workers are the Executor's choice when supported and worthwhile. Missing optional subagents does not block the main Executor. A real technical STOP affects the failing operation; keep the larger approved workstream open and continue independent admitted stages. Retain the existing GitHub cursor for GitHub-backed work or the available local result/handoff for local-only work. No unattended continuation across a closed host session is promised without a real host scheduling mechanism.

## Practical Work Director workflow

Start from the Owner-approved result and, for GitHub-backed work, the existing repository/Issue. Local-only work starts from the selected target and applicable user/project authority. Let Work choose the smallest appropriate number of **distinct native Work Subagents, Codex workers or other admitted agents** for implementation. A Work Director does not implement its own governed change; it may fully review a separate Executor's exact candidate at V1–V4. Use a separate Verifier when another assessor is specifically required or useful; a genuine Work Subagent may fill that role when it did not implement the candidate and can read the required evidence. Never relabel the Director's review as a separate Verifier result.

For GitHub-backed assignments, use the existing GitHub connector, native tools and current capability evidence; the agent publishes the exact authorized GitHub candidate and retains applicable review and production gates. Local-only work uses its selected local destination and actual evidence without a GitHub candidate. In either mode, respect Owner/Canon, do not reauthenticate, rerun provider setup, search old agent chats on cold start or manufacture a full administrative packet for every routine operation. Check only a genuinely new/missing capability or materially changed target.

A stopped optional tool operation or repair stream blocks only the dependent operation, not independent approved work. Retain the existing Issue cursor for GitHub-backed work or the available local result/handoff for local-only work and continue available stages. Do not promise an unattended wakeup after Work closes.

## Software delivery

- For an already approved bounded GitHub Software change, Director launches or reuses a **separate Executor** using Work's native Subagents, Codex Cloud or another approved capable host. Work autonomously chooses useful decomposition and optional subagents; no previous Executor is needed. The actual Executor publishes its own approved branch/Draft PR through an authorized GitHub tool. GitHub carries files and diffs; chats carry concise links, HEAD and role-native result references, not source dumps.
- For an approved multi-PR outcome, the **workstream** stays open after any child Assignment/PR is complete. Director maintains a short cursor in the existing governing Issue, independently reads new main after accepted merges, and advances the next already-authorized stage without asking Owner to reapprove ordinary continuation. Every stage still obeys its own admission, CI/Preview as relevant, required independent verification, promotion authority and anti-loop limits.
- Reuse suitable current Work Subagent, Codex or Verifier instances when role, exact-state capabilities and independence permit. A terminated session may need a fresh agent reconstructed from applicable GitHub state or an existing HANDOFF; local-only work may continue from its available local result or handoff. Do not promise unattended resumption without a proven transport.
- When the required current external tools are unavailable, identify the exact missing capability and use the existing WAIT/ESCALATE and Owner-actionability rules. Do not install/provision a replacement system or fabricate completion.

## Git-first work preservation

For any GitHub-backed code-changing Software task, confirm the selected Executor/publisher can publish a real GitHub PR or approved remote branch **before local edits**. Temporary working directories are execution surfaces, not durable project state. The same authorized remote PR/branch is the checkpoint across substantive work turns: publish in-scope WIP there before returning control, ending/rotating a session or discarding a temporary checkout. Failed tests or incomplete work remain **Draft / NOT READY**, not a successful candidate.

For GitHub-backed work, after each Executor return, Director independently reads the exact remote HEAD. A locally claimed commit or successful check without a published/refreshed remote candidate is unfinished publication, not completion. Keep the original attempt and Director baton; never ask Owner to rescue code, fabricate a commit, launch a parallel PR or switch to retired transport. If publication is truly unavailable, report a scoped `PARTIAL/BLOCKED` and preserve the original workspace without claiming the source has been saved. Existing verification and CI requirements apply before promotion, not as a reason to withhold an honest WIP checkpoint.

## Exit

Return the actual bounded result, exact current state, outstanding evidence, and the next action owner. Workstream COMPLETE requires evidence for the final approved Owner result, not just a successful child PR. For tasks that actually require canonical source, this package remains a thin entry adapter; the packaged local-only procedure does not require that source to be online.

## Anti-patterns
Do not fabricate destination access, local-profile loading, shell isolation, independent verification or durable publication. Do not create local setup requirements for remote-only tasks.

## Minimal verdict format
State actual task result, exact durable reference and any relevant local profile/capability limitation; distinguish source policy from live enforcement.