# Skill Intent Resolution

CTM must not treat skill autocomplete as an automation contract. Autocomplete answers
"what might the user be typing?" while mobile worktree actions ask "which skill can
perform this operation for this agent?" Those are different problems.

## Goals

- Route phone worktree actions to the selected owning coding session instead of
  mutating git directly from CTM.
- Choose the best available skill for each user and machine. Do not assume the
  user has `tl-commit`.
- Respect agent dialects: Codex-style skills use `$skill`; Claude Code skills use
  `/skill`.
- Avoid message-only skills such as `writing-commit-messages` for operations that
  need to review, commit, merge, or create pull requests.
- Cache capability knowledge in the CTM process. A CTM restart rebuilds the cache
  from the local skill registry, so newly installed or edited skills are picked up
  without persistent migration state.

## Contract

The backend exposes:

`GET /api/skills/resolve-intent?intent=<intent>&agent=<agent>&cwd=<cwd>`

Supported intents:

- `commit_main`: review and commit local changes in the main checkout.
- `finish_and_merge`: review, commit intended changes, validate, and integrate a
  worktree branch into local main.
- `create_pr`: review/commit as needed, push if needed, and create a pull request.

The response contains the selected skill, invocation prefix, inferred capabilities,
and a small ranked candidate list for diagnostics.

## Capability Model

Skills can declare explicit metadata:

```yaml
capabilities:
  - git.review
  - git.commit
  - git.merge.main
invocation: $
```

Legacy skills still work. The resolver infers capabilities from name,
description, source, and existing agent compatibility metadata. Explicit
capabilities win over inferred text, but inference is intentionally conservative:
`commit message` means message composition, not git commit authority.

## Caching

`lib/skill-autocomplete.js` caches parsed skill files by workspace. The intent
resolver adds a second in-memory cache keyed by `cwd + agent + intent` for the
ranked capability result. The cache is process-local by design:

- CTM restart = fresh parse and fresh intent cache.
- No persistent cache table means no stale cross-version schema or migration.
- Tests can clear the cache with `clearSkillIntentCache()`.

## Mobile UX

The phone worktree sheet asks the backend for the action intent instead of
querying autocomplete for broad words like `commit`, `review`, and `merge`.

If no eligible skill is found, CTM sends a plain-language prompt to the selected
session. That fallback is deliberate and safer than invoking a weak match. The
selected agent remains responsible for git state, validation, and reporting
blockers.
