# Workflow skill mount across runtimes (#551)

## Problem

Controller prompts require **`gitea-workflow`**, but:

- Claude may load `~/.claude/skills/gitea-workflow`
- Codex often has **no** `~/.codex/skills/gitea-workflow`
- The portable package in-repo is `skills/llm-project-workflow`
- `mcp_list_project_skills` historically listed operational guides only, not
  the workflow router

Sessions then either **block** incorrectly or **proceed without** the workflow
wall.

## Canonical names (must resolve to the same skill)

| Name | Use |
|------|-----|
| `gitea-workflow` | **Primary** controller / Codex skill name |
| `llm-project-workflow` | Portable in-repo package name |
| `git-pr-workflows` | Legacy alias |

Source of truth: `skills/llm-project-workflow/SKILL.md`  
In-repo alias stub: `skills/gitea-workflow/SKILL.md`

## Codex install

From a `branches/` worktree (or any clone of the repo):

```bash
./scripts/install-codex-workflow-skill.sh
# optional:
./scripts/install-codex-workflow-skill.sh --dry-run
./scripts/install-codex-workflow-skill.sh --skills-dir "$HOME/.codex/skills"
```

This symlinks the portable package under all three names. **Restart Codex**
after install.

## MCP discovery

- `mcp_list_project_skills` includes `gitea-workflow`, `llm-project-workflow`,
  and `git-pr-workflows`.
- `mcp_get_skill_guide("<name>")` returns the same router steps for each.
- `mcp_check_workflow_skill_preflight` proves the in-repo skill file exists and
  reports Codex mount status.

## Preflight rule

Before any git or Gitea mutation:

1. Call `mcp_check_workflow_skill_preflight`.
2. If `blocked` / `workflow_skill_ready` is false → **BLOCKED + DIAGNOSE**; do
   not mutate.
3. Load the skill by **any** canonical name and follow the router.

Missing Codex mount alone does not block if the in-repo skill is present and
loaded via MCP/docs; operators should still install the Codex symlink so
prompt names resolve natively.

## Controller prompts

Prefer:

> Invoke skill `gitea-workflow` (alias of `llm-project-workflow`).

Do not require a name that is only available on one runtime.