Feature: let the captain configure which skill runs at each workflow phase

[acho1833]

Summary

Firstmate already lets me choose who does the work (config/crew-dispatch.json picks harness, model, and effort per kind of task). It does not let me choose how the work is done.

The workflow steps themselves are fixed. no-mistakes is the validation skill, and phases like planning and code review have no skill hook at all. I have my own skills that I trust for those phases and I want firstmate to use them.

I'd like a local, gitignored config file that maps a workflow phase to a skill, so that:

• when a crewmate does planning work → it uses my grill-with-docs skill
• when a crewmate does code review → it uses my thermo-nuclear-code-quality-review skill

Same idea as config/crew-dispatch.json, just one axis over: that file answers which agent, this one answers which skill.

---

The problem today

I have a working style I like. It lives in skills I've written and refined. Today there are only three ways to get firstmate to use them, and none of them work well:

1. Type it into every task. I have to remember to tell the first mate "use grill-with-docs for the planning" on every single dispatch. Miss one and the crewmate quietly does it the default way. It doesn't scale past a couple of tasks, which defeats the point of running a crew.
2. Write it as prose in data/captain.md. This is a preferences file, not a dispatch contract. It's a nudge, not a rule — it may or may not be applied, and there's nothing that fails loudly when a skill name is wrong or missing.
3. Fork AGENTS.md. This works, but AGENTS.md is the shared, tracked orchestrator file. Editing it to hold my personal skill choices means my private preferences now live in tracked, shared material, and I fight a merge every time upstream changes. The repo's own tracking principle says shared things are tracked and personal things aren't — my skill preferences are personal.

So there is currently no supported place to put "this is my workflow" and have it actually stick.

---

What I want

A local, gitignored file — config/crew-skills.json — that firstmate reads before dispatching and before driving a phase transition:

{
  "phases": {
    "plan":   { "skill": "grill-with-docs" },
    "review": { "skill": "thermo-nuclear-code-quality-review" }
  }
}

That's the whole minimum viable version. Two lines of config and my crew works the way I work.

With per-project overrides

Different projects deserve different rigor. My side project doesn't need the nuclear option; my production service does:

{
  "phases": {
    "plan":   { "skill": "grill-with-docs" },
    "review": { "skill": "thermo-nuclear-code-quality-review" }
  },
  "projects": {
    "my-side-project": {
      "review": { "skill": "quick-sanity-review" }
    }
  }
}

Resolution order

Most specific wins, and it should fall back cleanly to today's behavior:

1. an explicit instruction from me in chat for this one task ("plan this one with grill-with-docs")
2. the projects.<name> entry for the project the task belongs to
3. the top-level phases entry
4. today's built-in default (no extra skill, no-mistakes where the delivery mode calls for it)

A captain with no config file sees zero change in behavior.

---

Suggested phases

I'd start with a small, fixed set of names that match firstmate's existing vocabulary rather than inventing new concepts:

Phase	When it fires	Applies to
plan	crewmate is investigating, planning, or writing up findings	scout tasks
implement	crewmate is writing the change	ship tasks
review	the change is written and needs a quality pass before delivery	ship tasks
validate	the delivery gate runs	ship tasks (no-mistakes mode)

Starting with just plan and review would already cover my case and most of what people are likely to ask for. The rest can come later.

---

Why I think this fits firstmate

This isn't a new concept — it's the existing one applied to a second axis.

config/crew-dispatch.json is the exact precedent. It's a local, gitignored JSON file of natural-language rules that firstmate resolves with judgment, validated at bootstrap, inherited into secondmate homes, and never mixed into tracked shared material. Everything I'm asking for could follow that same pattern, and a captain who already understands crew dispatch would understand this immediately.

It respects the tracking principle. AGENTS.md stays the shared orchestrator. My skill preferences stay local and gitignored, next to crew-harness, crew-dispatch.json, and backend. Nothing personal ends up in tracked files, and I never fight a merge to keep my workflow.

It's the missing half of dispatch. Right now I can say "send the hard tasks to a strong model" but not "and have it review its work the way I review mine." Those two decisions belong side by side.

If you'd rather not add a second file, folding a "skills" key into config/crew-dispatch.json would satisfy me just as well — I care about the capability, not the filename.

---

Guardrails I'd expect

I want to be clear that I am not asking to weaken the delivery gate.

• The no-mistakes gate stays authoritative. For no-mistakes-mode projects, my review skill should run in addition to the pipeline, not instead of it. If a captain ever wants to actually replace it, that should be an explicit, separate, obviously-scary opt-in — not something you get by filling in review. Default is additive.
• Fail loudly, not silently. If a configured skill doesn't exist, or the JSON is malformed, bootstrap should report it the way an invalid crew-dispatch.json is reported today (CREW_SKILLS: invalid config/crew-skills.json - ...) and refuse to quietly fall back. A skipped review is worse than a stopped dispatch.
• Reuse the existing harness knowledge for invocation. The harness-adapters skill already owns the per-harness skill-invocation syntax (/<skill> for claude, grok, and kimi; $<skill> for codex; natural language where no form is verified). This feature should call into that, not restate it — and on a harness with no verified invocation form, degrade to a natural-language instruction in the brief rather than sending a command that won't land.
• Both skill locations should work. My skills are user-level (~/.claude/skills/), not vendored into the firstmate repo. Repo-level .agents/skills/ names should work too.
• Record it in task meta. Writing the resolved skill into state/<id>.meta (e.g. skill_review=) the way harness=, model=, and effort= are recorded today would make it debuggable when a task didn't do what I expected.

---

Acceptance criteria

• A captain can create config/crew-skills.json, name a skill for plan and review, and every subsequent crewmate uses those skills without further prompting.
• Absent config file → behavior is byte-identical to today.
• A per-project entry overrides the fleet-wide default for that project only.
• An explicit in-chat instruction for one task overrides the config for that task only.
• A malformed file or unknown skill name is reported at bootstrap and blocks dispatch rather than silently falling back.
• The file is gitignored and listed in docs/configuration.md, with a copyable starting point under docs/examples/.
• For no-mistakes-mode projects, the configured review skill runs alongside the pipeline; the gate is not bypassed.
• The resolved skill per phase is recorded in the task's meta.

---

Alternatives I considered

Option	Why it doesn't work
Prose in data/captain.md	It's a preferences file, not a contract. No validation, no guarantee it's applied, no per-project scoping.
Editing AGENTS.md	Puts personal choices in tracked shared material and creates a permanent merge conflict with upstream.
Telling the first mate every task	Doesn't scale, and a forgotten instruction fails silently.
Wrapping my skills into one mega-skill	Doesn't help — there's still no hook that says when to invoke it.

---

My use case, concretely

I run several projects through firstmate. My planning skill (grill-with-docs) forces a crewmate to actually read the docs and interrogate its own assumptions before it writes a line — it catches bad plans early, which is the cheapest place to catch them. My review skill (thermo-nuclear-code-quality-review) is a deliberately harsh quality pass that I trust more than a generic review.

These two skills are my workflow. Right now firstmate gives me a great crew that doesn't work the way I do, and I have to choose between re-typing my workflow forever or forking the orchestrator. A small config file solves it, follows a pattern the project already uses, and costs nothing for captains who never create the file.