feat(skills): add issue-workflow skill and fm-brief --plan#676
Open
KaedinHanohano-Plexis wants to merge 6 commits into
Open
feat(skills): add issue-workflow skill and fm-brief --plan#676KaedinHanohano-Plexis wants to merge 6 commits into
KaedinHanohano-Plexis wants to merge 6 commits into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds the
issue-workflowskill and a--planflag tobin/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.sha 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 (writedata/<id>/plan.md, scaffold withfm-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.mdis a symlink toAGENTS.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 planblock 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.fm-instruction-owners,fm-captain-translation-contract,fm-update.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):
--plan. The plan specified only ship-mode behavior. The undefined cases are rejected loudly, matching the script's existing--herdr-lab/--no-projectsguards:--planon scout/secondmate briefs, a bare--planwith no path, and an empty-string path.--planpath 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.forloop to awhileloop so--plancan consume its value argument.No AI attribution is included in any commit or this description.