Skip to content

feat(skills): add issue-workflow skill and fm-brief --plan#676

Open
KaedinHanohano-Plexis wants to merge 6 commits into
kunchenguid:mainfrom
KaedinHanohano-Plexis:fm/wf-skill-7q
Open

feat(skills): add issue-workflow skill and fm-brief --plan#676
KaedinHanohano-Plexis wants to merge 6 commits into
kunchenguid:mainfrom
KaedinHanohano-Plexis:fm/wf-skill-7q

Conversation

@KaedinHanohano-Plexis

Copy link
Copy Markdown

What

Adds the issue-workflow skill and a --plan flag to bin/fm-brief.sh, codifying the standing "work an issue" workflow into the shared template.

Why

The workflow of pick → grill → scope-for-approval → dispatch one crewmate per issue was operator knowledge that lived only in habit. This makes it a first-class, self-contained skill any firstmate can load, and gives fm-brief.sh a way to bind a dispatched crewmate to a captain-approved plan.

Changes

  • .agents/skills/issue-workflow/SKILL.md (new): agent-only skill (metadata.internal: true, user-invocable: false) owning the workflow's ordering and per-step contract — trigger & repo resolution + issue ranking, an embedded self-contained grill protocol, the lavish scope contract (one ticket per artifact, mandatory sections), approval → dispatch (write data/<id>/plan.md, scaffold with fm-brief --plan, spawn one crewmate on the execution profile), and ship rules (deviation threshold, PR hygiene, captain merges). It points at existing machinery (fm-brief, fm-spawn, backlog verbs, section 8 supervision) rather than restating lifecycle mechanics, per the repo's one-owner rule, and stays generic (no model- or captain-specific config).
  • AGENTS.md: two pointer lines only — a section 7 intake trigger and a section 13 agent-only skill row. No other sections changed. (CLAUDE.md is a symlink to AGENTS.md, so it is not edited separately.)
  • bin/fm-brief.sh: new --plan <path> flag. When set on a ship brief, it injects an # Approved plan block after the Task section declaring the plan binding and stating the deviation threshold. The disclosure destination is mode-aware: the PR body for PR-producing modes (no-mistakes, direct-PR), or the final ready-branch done summary for local-only (which opens no PR). The path is validated (non-empty, exists, ship-only) and absolutized so a crewmate reading it from an isolated worktree resolves it. Without the flag, scaffold output is byte-identical to before.
  • tests/fm-brief.test.sh: coverage for block injection, path/scope/empty validation, mode-aware disclosure, and byte-identical no-flag output.

Verification

  • tests/fm-brief.test.sh: 17/17 pass.
  • Related suites green locally: fm-instruction-owners, fm-captain-translation-contract, fm-update.
  • No-flag scaffold output confirmed byte-identical by diffing against the pre-change script.
  • Validated through the local gate (review, document steps clean). The full e2e suite and shellcheck lint are left to CI here, since this environment lacks jq, herdr, and ShellCheck; the failures observed locally were confined to those tool-absent tests and never to changed code.

Deviations from approved plan

All minor (the plan reserves wording, ordering, and test naming as adaptable):

  1. Extra fail-closed guards on --plan. The plan specified only ship-mode behavior. The undefined cases are rejected loudly, matching the script's existing --herdr-lab/--no-projects guards: --plan on scout/secondmate briefs, a bare --plan with no path, and an empty-string path.
  2. Mode-aware deviation-disclosure destination. Rather than always "the PR body," the injected block routes disclosures to the PR body for PR-producing modes or the ready-branch done summary for local-only, which has no PR. (A review pass surfaced that a local-only brief has no PR body; resolved by this mode-aware wording.)
  3. --plan path absolutization. The caller-supplied path is absolutized after the existence check so a crewmate in an isolated worktree resolves it, matching how the brief already embeds the status-file and report paths.
  4. Three new test functions were added rather than folded into the existing scaffold test.
  5. Arg parsing was converted from a for loop to a while loop so --plan can consume its value argument.

No AI attribution is included in any commit or this description.

KaedinHanohano-Plexis and others added 6 commits July 16, 2026 09:49
Codify the standing issue workflow (pick, grill, scope for approval,
single-crewmate dispatch) as a shared internal skill, and add a
--plan flag to fm-brief.sh that injects a binding-plan block into
ship briefs.

- .agents/skills/issue-workflow/SKILL.md: new agent-only skill owning
  the workflow ordering and per-step contract; points at existing
  machinery (fm-brief, fm-spawn, backlog, section 8) rather than
  restating lifecycle mechanics.
- AGENTS.md: section 7 intake pointer and section 13 trigger row.
- bin/fm-brief.sh: --plan <path> flag; validates the path, ship-only,
  injects the Approved plan block with the deviation threshold.
  Byte-identical scaffold output without the flag.
- tests/fm-brief.test.sh: cover injection, path/scope validation, and
  byte-identical no-flag output.
An empty --plan value (e.g. from an unset shell variable in --plan "$VAR")
passed the bare-flag guard and set PLAN_PATH="", which the later non-empty
gate then treated as no flag - scaffolding the brief without the binding-plan
block silently. Reject an empty value loudly so it fails closed like the
flag's other undefined cases (bare --plan, missing file, non-ship brief).
Replace the local-only rejection with mode-aware disclosure wording. --plan
is accepted for every ship mode again; the deviation-disclosure destination
adapts to the delivery path: the PR body for PR-producing modes (no-mistakes,
direct-PR), or the final ready-branch done summary for local-only, which opens
no PR. Keeps the skill's deviation threshold consistent with the generated
block and preserves byte-identical no-flag scaffold output.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant