council
Use when the user runs /council [ticket-id]. Convenes a planning council on an issue tracker ticket. Erestor (subagent) drafts a plan, posts it as a ticket comment, and waits for the human's verdict.
SKILL.mdskills/council/SKILL.md
GitHubCouncil
Convenes a planning council on a tracker ticket. A subagent — Erestor, chief counsellor of Imladris — drafts a plan from the ticket's text. The plan is posted as a comment. The human — Elrond — renders verdict through further comments. Each /council TICKET-ID turns the wheel another round.
Ethos
- Elrond decides. The human holds every verdict. The Council never acts in their name.
- Erestor counsels. He reads, he drafts, he asks when he must. He does not approve, reject, or act.
- The thread is the record. Every plan, every question, every verdict is a comment on the ticket. No side channels.
Argument parsing
/council [ticket-id]
ticket-id: the tracker's ticket identifier (e.g.YT-123). If omitted, ask the user via AskUserQuestion.
Tracker routing
Two trackers are wired today:
| Tracker | Fetch hook | Comment hook |
|---|---|---|
| YouTrack | ~/.claude/hooks/council-youtrack-fetch.sh |
~/.claude/hooks/council-youtrack-comment.sh |
| Jira | ~/.claude/hooks/council-jira-fetch.sh |
~/.claude/hooks/council-jira-comment.sh |
Hybrid dispatch rule. Resolve the tracker for a given /council [tracker:]TICKET-ID invocation in this order:
Explicit override. If the argument carries a tracker prefix —
youtrack:MET-1,yt:MET-1,jira:PSG-4264— that wins. Strip the prefix and use the remainder as the ticket ID. Acceptyoutrackoryt; acceptjira. Case-insensitive.Per-project memory. Read
tracker_routing.mdfrom the project memory directory. The file maps a project key prefix to a tracker:--- name: Tracker Routing description: Project-key prefix to tracker mapping for /council, /celebrimbor, and /mandos. type: reference --- - MET → youtrack - PSG → jiraMatch the prefix of the ticket ID (
MET-1→ prefixMET) against the table; if found, use the named tracker.Ask. No prefix override, no memory mapping — ask the user via AskUserQuestion which tracker to use, then offer to save the mapping to memory for next time.
Once the tracker is chosen, all subsequent steps use that backend's hooks. The ticket-ID prefix itself is just a project shortName; do not hardcode any list of valid prefixes.
Jira read-only rule. When smoke-testing or otherwise running the council in a non-production capacity, treat Jira tickets as read-only — do not post comments. The Jira comment hook accepts COUNCIL_DRY_RUN=1 in env to print the would-be ADF payload instead of posting. Use that for shape verification.
Working-directory contract
Erestor's working directory comes from a per-project memory file repo_routing.md, not from the user's current shell pwd. Resolution order:
Memory mapping. Read
repo_routing.mdfrom the project memory directory.- Single-repo (default). Look up
<tracker>:<project>(e.g.youtrack:MET). If found, that's the source repo path. If the value is(no repo), tell Erestor explicitly that this ticket has no codebase context — he drafts from ticket text alone, and the worktree step below is skipped. - Multi-repo (sub-keyed). A project whose tickets span several repos declares sub-keyed entries instead — a line whose key carries a third segment,
<tracker>:<project>:<tag>(e.g.jira:PSG:APP,jira:PSG:WEB). To detect the case, scanrepo_routing.mdfor any line keyed with the<tracker>:<project>:prefix; when one or more exist, this project is multi-repo and the bare key is not used. Derive the tag from the ticket summary: scan its leading bracket tags[…]for the first that matches a declared sub-key (case-insensitive), then look up<tracker>:<project>:<tag>for the source repo path ((no repo)honoured as above). A summary bearing no matching sub-key tag has no repo for this ticket — treat it as(no repo)(Erestor drafts from ticket text, worktree skipped) and say so plainly. Tags that are not sub-keys — region or flavour markers like[NA],[JP]— are ignored for routing; only the declared layer tags steer the tree.
- Single-repo (default). Look up
Ask and save. If no entry, prompt the user via AskUserQuestion with options:
- "Current cwd" — capture
git rev-parse --show-toplevel(or the cwd if not a repo) and save. - "A specific path" — let the user type one (the AskUserQuestion "Other" affordance).
- "No repo" — save
(no repo)for this project.
Save the chosen value to
repo_routing.mdunder the<tracker>:<project>key, then proceed.- "Current cwd" — capture
Wrap the source in a worktree. Erestor does not read the source repo directly — the human may be editing files there, and a concurrent Read against unsaved edits would mislead the draft. Instead, acquire an isolated detached-HEAD workspace via the shared helper:
~/.claude/hooks/skadi-worktree.sh acquire <source-repo>The helper prints the workspace path on stdout. It tries
git worktree add --detachfirst (fast — shares the object store); on failure it falls back to a temp clone under$TMPDIR. Either way, the workspace pins to the source repo's HEAD at acquire time and lives under$TMPDIR/skadi-…. Hold the path; this — not the source repo — is what Erestor sees.When the source value is
(no repo), skip this step.Use the workspace path as Erestor's working directory and pass it in his prompt. He may Read / Grep / Glob /
git logthere. He must not modify anything.
This decouples where you happen to be from which repo this ticket concerns, and the worktree wrap decouples what Erestor reads from whatever the human happens to be editing right now. To change the binding for a project, edit repo_routing.md. To re-prompt, delete the project's line.
Workflow
0. Resolve the tracker
Apply the Hybrid dispatch rule from "Tracker routing" above to choose between YouTrack and Jira. The remainder of these steps refer to <fetch-hook> and <comment-hook> — substitute the chosen tracker's pair from the routing table.
YouTrack credentials. One Vaultwarden item named youtrack: URI = server URL, password = permanent token. Hooks resolve via secret.sh youtrack uri / secret.sh youtrack. Env fallback: $YOUTRACK_URL / $YOUTRACK_TOKEN. Token comes from <YOUTRACK_URL>/users/me?tab=account-security.
Jira credentials. One Vaultwarden item named jira: URI = https://<your>.atlassian.net, username = your email, password = an API token. Hooks resolve via secret.sh jira uri / secret.sh jira username / secret.sh jira password JIRA_API_TOKEN. Env fallback: $JIRA_BASE_URL / $JIRA_EMAIL / $JIRA_API_TOKEN. Token comes from https://id.atlassian.com/manage-profile/security/api-tokens.
If any credential cannot be resolved, the hook prints {"error":"jira credentials missing"} (or YouTrack equivalent) — surface it and stop.
Rendering the plan: Henneth mirror and diagram/wireframe embed
Before every post or edit of a plan comment — draft or redraft, either
tracker — run this pipeline on Erestor's returned body ($EREST_OR_BODY).
It is invoked from four call sites: the YouTrack modify-only path's
draft_plan/await_start and redraft_plan branches below, and the Jira
path's step 6 first-turn-create and redraft-edit branches. It does not
run on [PEDO]/[PARLEY] — the plan body is unchanged in both cases, so
there is nothing fresh to mirror or scan.
1. Render the Henneth mirror. Write Erestor's full returned body to Henneth so it can be read locally:
printf '%s' "$EREST_OR_BODY" | python3 ~/.claude/hooks/council-plan-html.py render-plan <TICKET-ID> ~/.skadi/henneth/plan-<TICKET-ID>.html
This always runs, on every draft and redraft — independent of whether a diagram/wireframe block is present and independent of tracker-post success.
2. Detect a diagram or wireframe. Scan the same body for a fenced block:
DETECT_OUT=$(printf '%s' "$EREST_OR_BODY" | python3 ~/.claude/hooks/council-plan-html.py detect)
DETECT_STATUS=$?
If $DETECT_STATUS is 1 (no block found — $DETECT_OUT is NONE), skip
straight to posting/editing the comment with $EREST_OR_BODY unchanged; none
of the remaining sub-steps run. If $DETECT_STATUS is 0, the first line of
$DETECT_OUT is FOUND tag=<diagram|wireframe> and the rest is the raw
block body — extract both and continue:
DIAGRAM_TAG=$(printf '%s' "$DETECT_OUT" | head -1 | sed 's/FOUND tag=//')
DIAGRAM_BODY=$(printf '%s' "$DETECT_OUT" | tail -n +2)
3. Render and screenshot the block. Write the block alone to a scratch
HTML file, then screenshot it — reusing the same pipeline /celebrimbor --skeleton uses for its diagram PNG (skills/celebrimbor/SKILL.md:152):
printf '%s' "$DIAGRAM_BODY" | python3 ~/.claude/hooks/council-plan-html.py render-diagram <TICKET-ID> "$TMPDIR/diagram-<TICKET-ID>.html"
npx -y playwright screenshot "$TMPDIR/diagram-<TICKET-ID>.html" "$TMPDIR/diagram-<TICKET-ID>.png"
If either command fails (non-zero exit), stop the diagram pipeline here: log
the failure so it can be named in the round's report (see the report-format
addition in Report and release below), and post/edit the comment with
$EREST_OR_BODY unchanged (the fenced block posts as raw ASCII, exactly
as council would with no preview pipeline at all) — do not attempt the
attach/embed sub-steps below.
4. Attach, then embed — per tracker. Still within the same conditional (a diagram/wireframe block was found and screenshotted successfully), do this before the tracker's post/edit call:
YouTrack:
~/.claude/hooks/youtrack-attach.sh <TICKET-ID> "$TMPDIR/diagram-<TICKET-ID>.png"On success, replace the fenced block in the body before posting/editing:
printf '' > "$TMPDIR/img-ref.txt" EREST_OR_BODY=$(printf '%s' "$EREST_OR_BODY" | python3 ~/.claude/hooks/council-plan-html.py replace "$TMPDIR/img-ref.txt")On failure, leave
$EREST_OR_BODYunchanged (raw ASCII posts) and note the failure for the round's report.Jira:
ATTACH_OUT=$(~/.claude/hooks/jira-attach.sh <ISSUE-KEY> "$TMPDIR/diagram-<TICKET-ID>.png")On success,
$ATTACH_OUTisattached: name=... id=<ATTACHMENT-ID> url=...— extract<ATTACHMENT-ID>and replace the fenced block with the sentinel:JIRA_ATTACHMENT_ID=$(printf '%s' "$ATTACH_OUT" | sed -n 's/.*id=\([^ ]*\).*/\1/p') printf '[[PLAN-PREVIEW]]' > "$TMPDIR/sentinel.txt" EREST_OR_BODY=$(printf '%s' "$EREST_OR_BODY" | python3 ~/.claude/hooks/council-plan-html.py replace "$TMPDIR/sentinel.txt")JIRA_ATTACHMENT_IDmust reachcouncil-jira-comment.shorjira-comment-edit.shon the same command that invokes the hook for this round (both hooks read it from the environment) — prefix that invocation withJIRA_ATTACHMENT_ID="$JIRA_ATTACHMENT_ID"rather than exporting it as a standing variable here; a later code block is a separate invocation, and a standing export would not survive into it. On attach failure, leave$EREST_OR_BODYunchanged, do not setJIRA_ATTACHMENT_ID, and note the failure for the round's report.
YouTrack modify-only path (skeleton-stage pipeline)
When the resolved tracker is YouTrack, council maintains a single living
[PLAN] comment instead of appended [COUNSEL vN] versions, and follows this
path instead of steps 1–7 below. (The Jira path below also maintains a single
living plan comment, edited in place — it keeps its own thread parser and a
visible [COUNSEL vN] marker, but the plan body is no longer re-appended each
round.)
Fetch + decide. Run the fetch hook, pipe to the decider:
~/.claude/hooks/council-youtrack-fetch.sh <TICKET-ID> > /tmp/thread.json action_line=$(~/.claude/hooks/skeleton-rung.py < /tmp/thread.json)Parse
action=andplan_id=fromaction_line.Branch on the action:
draft_planorawait_start— summon Erestor (worktree per the Working-directory contract); he drafts the plan body.await_startmeans the thread bears no[MELLON]summons, but reaching/councildirectly is the summons (the invocation is consent), so it drafts exactly asdraft_plandoes. Erestor still returns his[COUNSEL vN]envelope; strip that envelope and wrap his body as the[PLAN]comment. Create the comment with the marker, watermark, and body:[PLAN] — awaiting [FORTH] <!-- consumed: <newest-human-created-or-0> --> <Erestor's plan>Before posting, run the Henneth-mirror and diagram/wireframe pipeline (Rendering the plan above) on Erestor's returned body — it may swap the fenced block for an attached image. Then post the (possibly diagram-swapped) body as
<Erestor's plan>via~/.claude/hooks/council-youtrack-comment.sh <TICKET-ID>.redraft_plan— Elrond has posted[ENVINYA]/[ALTER], directing a change. Summon Erestor with the thread (including the alter instruction); he redrafts. Before editing, run the same Henneth-mirror and diagram/wireframe pipeline (Rendering the plan above) on Erestor's returned body. Edit the same comment in place via~/.claude/hooks/youtrack-comment-edit.sh <TICKET-ID> <plan_id>, with the watermark advanced to the newest human comment'screated. An in-place edit fires no thread notification, so append a[VINYA]notice afterwards via~/.claude/hooks/council-youtrack-comment.sh <TICKET-ID>(see The[VINYA]change notice below), so Elrond sees the plan was renewed.answer_plan— Elrond has asked a question ([CEIST]/[ASK], or bare prose), not directed a change. Summon Erestor in answer mode (see step 5): give him the standing[PLAN]body, the thread, and the question; he returns a[PEDO]body that answers without redrafting. Append it as a new comment via~/.claude/hooks/council-youtrack-comment.sh <TICKET-ID>. Then edit the[PLAN]comment via~/.claude/hooks/youtrack-comment-edit.sh <TICKET-ID> <plan_id>, advancing only its watermark to the newest human comment'screated(body otherwise unchanged) — this consumes the question so the next ride stays quiet. The plan body is never rewritten; only[ENVINYA]/[ALTER]does that.draft_skeleton—[FORTH]has just approved the plan; the skeleton rung itself belongs to celebrimbor, so council does not draft it. But this is YouTrack's approval moment: run The[ENWINA]divergence notice below, then report "awaiting (plan approved; skeleton is celebrimbor's)" — naming whether an[ENWINA]notice was posted — and stop.await_plan/redraft_skeleton/answer_skeleton/forge/done— no-op. Council's job is the plan rung only; later rungs belong to celebrimbor. Report "awaiting" and stop. (await_startis handled by the draft clause above — a direct invocation is consent.)
Watermark rule. Whenever council writes the
[PLAN]comment, set<!-- consumed: N -->to thecreatedof the newest human comment in the thread (0 if none). This is what makes the loop quiet between instructions.
1. Fetch the ticket and its comment thread
Invoke the chosen tracker's fetch script with just the ticket ID — credentials are resolved inside:
<fetch-hook> <TICKET-ID>
(The script pulls every credential via the secret helper; do not echo or log them.)
The script prints a single JSON object:
{
"summary": "...",
"description": "...",
"comments": [
{ "author": "...", "login": "...", "text": "...", "created": 1700000000000 },
...
]
}
If the script prints {"error": "..."}, tell the user the error and stop.
The steps below apply to the Jira path only. The YouTrack path is handled by the modify-only section above and does not reach here. The Jira path keeps the thread parser and the
[COUNSEL vN]marker, but maintains a single living plan comment edited in place (step 6): the first turn creates[COUNSEL v1]; each[ENVINYA]redraft edits that same comment (version bumped) and appends a[VINYA]change notice. Only[PEDO]answers and[PARLEY]are still appended.
2. Parse the thread
Walk the comments array (already oldest-first). Determine:
Latest plan version. The highest
Nwhere a comment's first line matches[COUNSEL vN]or its alias[PLAN vN](case-insensitive). If no plan exists yet, the next version is1.Plan comment id. The
idof that highest-version plan comment (from the fetch hook'sidfield). This is the comment step 6 edits in place on a redraft. If no plan exists yet, there is no id — step 6 creates the comment instead.Bot identity. Two modes:
- Service-account mode (e.g. YouTrack with a dedicated
claudeuser): a comment is the bot's ifflogin == "<bot-login>". - Shared-identity mode (e.g. Jira where the bot posts as Elrond): no login distinction exists; a comment is the bot's iff its first line carries
[COUNSEL v…]/[PLAN v…](alias),[PARLEY]/[AGENT-ASK](alias),[PEDO]/[ANSWER](alias),[VINYA]/[RENEWED](alias — the in-place-edit notice),[ENWINA]/[STALE](alias — the description-drift notice),[DOOM]/[VERDICT](alias — Mandos's faithfulness verdict, loop-neutral),[GWAITH]/[FORGED]/[SHIPPED](Celebrimbor's mark),[SKELETON](Celebrimbor's opt-in skeleton rung), or[METTA](Aulë's close-on-merge).hooks/jira-skeleton-rung.pyapplies this same list.
Detect mode by inspecting the comment thread: if any login carries the configured bot value (today:
claude), use service-account mode; otherwise use shared-identity mode.- Service-account mode (e.g. YouTrack with a dedicated
Bot's last word. The most recent comment classified as the bot's under the chosen mode. If no bot comment exists yet, this is the first turn.
Fresh counsel. Any comments after the bot's last word that are not the bot's under the chosen mode. These are Elrond's counsel. If none exist, the thread has not moved since the bot last spoke.
Verdict. Scan the fresh counsel for any of these tokens (case-insensitive, anywhere in the body):
[FORTH]or its alias[APPROVE](yes);[NAY]or its alias[REJECT](no);[NAMARIE]or its alias[FAREWELL](adjourn without verdict).
3. Handle thread state
The order of these checks matters — skeleton beats verdict beats quiet (no fresh counsel) beats first-turn beats alter beats answer.
Skeleton standing (Jira). If the thread bears a bot
[SKELETON], the plan rung is closed and every later human word —[FORTH],[ENVINYA], a question — belongs to the skeleton, which is/celebrimbor --skeleton's to answer. Council posts nothing (a[PEDO]here would read as the bot's last word and swallow the skeleton question). Tell the user "awaiting — the skeleton is celebrimbor's" and stop. This mirrors the YouTrack path'sdraft_skeletonno-op.Verdict present. Scan all fresh counsel for the three verdict tokens (and their aliases). Token precedence — not chronological order — picks the winner:
[FORTH]/[APPROVE]beats[NAY]/[REJECT]beats[NAMARIE]/[FAREWELL]. So if Elrond posts[NAY]and later posts[FORTH], the parser adjourns as approved (FORTH wins regardless of when it appeared); same if the order is reversed. Effect:[FORTH]/[APPROVE]→ adjourn with approval on[COUNSEL vN]. Before stopping, run The[ENWINA]divergence notice below — on approval the plan is settled, so this is the one moment to flag a description that has fallen behind it.[NAY]/[REJECT]→ adjourn without approval.[NAMARIE]/[FAREWELL]→ adjourn without verdict (farewell — for out-of-band resolution).
Tell the user which adjournment fired and on which counsel version (and, for
[FORTH], whether an[ENWINA]notice was posted). Post nothing further. Stop.No fresh counsel and a plan already exists. The bot has spoken last and Elrond has not replied. Do not draft, do not post — there is no new ground to chew on, and a re-issue would only clutter the thread. Tell the user: "Awaiting Elrond's reply on
[COUNSEL vN](or the latest[PARLEY]). No fresh counsel since<timestamp>." Stop. This makes the skill loop-safe — repeated invocations between Elrond's replies are no-ops.First turn (no plan yet). Skip to step 4 to draft
[COUNSEL v1]. The ticket itself is the counsel; no prior bot word is required. A plan must exist before a question can be answered, so a bare question on a planless ticket drafts v1 rather than answering.Fresh counsel bearing
[ENVINYA]/[ALTER]. Elrond has directed a change. Fall through to the turn-limit check, then summon Erestor to redraft[COUNSEL vN+1].Fresh counsel without verdict and without
[ENVINYA]— a[CEIST]/[ASK], or bare prose. Elrond has asked, not directed. Summon Erestor in answer mode (step 5): he returns a[PEDO]body that answers the question without redrafting. Post it via the comment hook. Do not increment the counsel version, and skip the turn-limit check entirely — an answer is not a counsel and does not count toward the five-counsel limit. The bot's[PEDO]becomes its last word, so the next invocation finds no fresh counsel and stays quiet. Stop.
4. Check turn limit
The limit is on [COUNSEL vN] count, not invocation count — [PARLEY] posts do not count. If the next plan would be [COUNSEL v6] (i.e. five counsels already posted without verdict), do not draft. Post a single [PARLEY] comment via the comment script with this body:
[PARLEY] The council has turned five times without a verdict. This thread has outgrown what a comment can resolve. Take it offline — a conversation, a design doc, or a fresh ticket narrowed to one open question.
Then stop.
5. Summon Erestor
Acquire the isolated workspace per the Working-directory contract above (step 3 of the contract). The workspace path is what Erestor sees as his working directory; the source repo is untouched. If the contract's source value is (no repo), skip the acquire and tell Erestor he has no codebase context.
Load the Erestor prompt from <skill-dir>/erestor.md (read the file contents). Dispatch a subagent via the Agent tool, subagent_type: general-purpose, model: opus, passing:
- The Erestor prompt as the system/instruction portion of the Agent call's
prompt. - A tail block containing:
- The ticket
summaryanddescription. - The full comment thread (all
[COUNSEL v…],[PARLEY], and human comments in order, with author names). - The workspace path resolved above. If
(no repo)was the contract's verdict, state that plainly so Erestor knows not to attempt reads. - The instruction, by mode:
- Draft mode (first turn, or a
[ENVINYA]/[ALTER]redraft): "You are drafting[COUNSEL v{NEXT}]. Your working directory is the named workspace (or none, if so stated) — an isolated detached snapshot of the repo; you may read it with no writes, to verify assumptions before drafting. If a clarifying question is more honest than a guess, reply with a single[PARLEY]instead." - Answer mode (
answer_plan, or a Jira question without[ENVINYA]): "You are in answer mode. Elrond has asked a question of the standing plan, quoted below; answer it with a single[PEDO]body and do not redraft. The same read rules apply. If the question cannot be honestly answered from what you have, reply with a single[PARLEY]instead." Quote the standing[COUNSEL vN]/[PLAN]body and the question.
- Draft mode (first turn, or a
- The ticket
Erestor returns a single markdown body whose first line begins with [COUNSEL v{NEXT}], [PARLEY], or — in answer mode — [PEDO]. If he returns anything else, treat it as a drafting failure and stop — do not post. Even on drafting failure, release the workspace (see step 7) so it does not accumulate under $TMPDIR.
6. Post the comment
The Jira path keeps one living plan comment, edited in place. Branch on what Erestor returned and whether a plan already exists (the plan comment id from step 2):
[PEDO]answer or[PARLEY]— these are appends, never edits. Pipe the body to the comment hook as a new comment:printf '%s' "$EREST_OR_BODY" | ~/.claude/hooks/council-jira-comment.sh <ISSUE-KEY>[COUNSEL v{NEXT}]on the first turn (no plan comment id from step 2) — create the living plan comment. Before creating it, run the Henneth-mirror and diagram/wireframe pipeline (Rendering the plan above) on$EREST_OR_BODY— it may swap the fenced block for an attachment embed and, on Jira, setJIRA_ATTACHMENT_ID(thread it inline on the hook call below, which reads it from the environment):JIRA_ATTACHMENT_ID="$JIRA_ATTACHMENT_ID" printf '%s' "$EREST_OR_BODY" | ~/.claude/hooks/council-jira-comment.sh <ISSUE-KEY>[COUNSEL v{NEXT}]on a redraft (a plan comment id exists) — edit that comment in place, then append a[VINYA]change notice. Before editing, run the same Henneth-mirror and diagram/wireframe pipeline (Rendering the plan above) on$EREST_OR_BODY:JIRA_ATTACHMENT_ID="$JIRA_ATTACHMENT_ID" printf '%s' "$EREST_OR_BODY" | ~/.claude/hooks/jira-comment-edit.sh <ISSUE-KEY> <plan-comment-id> printf '%s' "$VINYA_BODY" | ~/.claude/hooks/council-jira-comment.sh <ISSUE-KEY>Compose
$VINYA_BODYper The[VINYA]change notice below. The edit must land before the notice; if the edit hook exits non-zero, surface the error and stop — do not post the notice (it would point at an unchanged plan).
The create/append hook prints posted: id=<comment-id> created=<epoch-ms> url=<full-ticket-url>;
the edit hook prints edited: id=<comment-id> url=<issue-url>. On failure either
prints {"error":"...","response":"..."} (the response field carries the
server's actual error body). If a script exits non-zero, tell the user the error
and stop.
The [VINYA] change notice
This notice serves both trackers — the Jira step 6 redraft branch above and
the YouTrack modify-only redraft_plan branch. A redraft edits the plan comment
silently — Jira and YouTrack fire no thread notification on an in-place edit, so
Elrond would never learn the plan moved. After the edit, council appends one
short [VINYA] (Quenya renewed, kin to Elrond's [ENVINYA] renew it)
comment via the tracker's plain comment hook (council-jira-comment.sh /
council-youtrack-comment.sh), recognized as the bot's word so the next ride
reads it as no fresh counsel. Point at the plan with the marker that tracker
uses — Jira's versioned [COUNSEL vN], YouTrack's bare [PLAN]:
# Jira (versioned marker):
[VINYA] The plan is renewed to v{NEXT} — see the [COUNSEL v{NEXT}] comment above.
# YouTrack (single living [PLAN]):
[VINYA] The plan is renewed — see the [PLAN] comment above.
The notice is composed by the skill body, not Erestor. It is the only append a redraft makes; the plan body itself is never re-appended. (The first-turn create needs no notice — a new comment already notifies.)
The [ENWINA] divergence notice
This notice serves both trackers — the Jira verdict branch (§3, check 1, on
[FORTH]) and the YouTrack modify-only draft_skeleton branch (the moment
[FORTH] advances the plan rung). Council posts it at most once per ticket:
when the accepted plan has outgrown the ticket's own description, it flags the
drift so Elrond can renew the description. It never rewrites the description —
council counsels through comments; the human's words are the human's to change.
Run it only at approval, in this order:
Idempotency guard. Scan the thread already fetched for any prior bot comment whose first line is
[ENWINA]/[STALE]. If one exists, do nothing — the drift was flagged already. Stop here.Compare. Read the approved plan body — Jira's latest
[COUNSEL vN], YouTrack's[PLAN]— against the ticketdescription(both from the fetch hook). Judge material divergence: at least one of- the plan adds scope the description never states,
- the description states scope the plan drops (its Not covered, or a silent omission),
- the plan's approach contradicts what the description says will be done.
Not divergence: added implementation detail, rewording, or elaboration consistent with the description. When in doubt, do not post — a false flag clutters the thread, and a description left as-is is recoverable.
Post — if and only if diverged. Compose the notice naming each drift point in one line; do not draft replacement description text. Post it via the tracker's plain comment hook (
council-jira-comment.sh/council-youtrack-comment.sh <TICKET-ID>), recognized as the bot's word so the next ride reads it as no fresh counsel:# Jira (versioned plan marker): [ENWINA] The approved [COUNSEL vN] has moved past the ticket description — the description is now stale and should be updated to match. What drifted: - <one line per divergence point> The plan on this thread is the source of truth for the forge.# YouTrack (single living [PLAN]): [ENWINA] The approved [PLAN] has moved past the ticket description — the description is now stale and should be updated to match. What drifted: - <one line per divergence point> The plan on this thread is the source of truth for the forge.The leading
[ENWINA]token is identical on both trackers — only the inner reference to the plan comment differs ([COUNSEL vN]vs[PLAN]). The notice is composed by the skill body, not Erestor, and is loop-neutral — it counts toward no turn limit and redrafts nothing.
7. Report and release
Tell the user, in one short block:
- The ticket ID.
- What council did this round —
[COUNSEL vN]created,[COUNSEL vN]edited in place (with the[VINYA]notice appended),[PARLEY], or[PEDO]. - The ticket URL printed on the success line in step 6.
- Whether a diagram/wireframe was found this round, and if so, whether it rendered and attached successfully or fell back to raw ASCII (name which tool failed, if any — screenshot or attach).
Do not reproduce Erestor's draft in the response — it lives on the ticket now.
Then release the isolated workspace, if one was acquired in step 5:
~/.claude/hooks/skadi-worktree.sh release <workspace-path>
The helper handles both worktree and temp-clone modes silently. Release on the success path and on the drafting-failure path (the workspace is ephemeral; nothing of value lives in it after Erestor returns). If Erestor never ran — verdict adjournment, loop-safe quiet, turn-limit [PARLEY] — no workspace was acquired, so nothing to release.
Comment grammar
Fourteen tokens carry state. Everything else is counsel.
| Token (primary) | Accepted alias | Who writes it | Meaning |
|---|---|---|---|
[COUNSEL vN] |
[PLAN vN] |
Erestor | A draft of the plan. N increments each round. The counsellor's counsel. |
[PARLEY] |
[AGENT-ASK] |
Erestor | A single clarifying question — speech between sides to come to terms. |
[PEDO] |
[ANSWER] |
Erestor / the smith | Speak, and answer. The reply to a [CEIST] (or bare question) — the plan stands untouched. Loop-neutral; uncounted toward the turn limit. |
[VINYA] |
[RENEWED] |
Council | Renewed. The notice appended after the living plan comment is edited in place (a silent edit fires no thread notification). Points at the renewed [COUNSEL vN]/[PLAN] above; the plan body lives there, not here. Loop-neutral. |
[ENWINA] |
[STALE] |
Council | Old — of the elder days. Posted once at approval when the accepted plan has outgrown the ticket description: the written account is stale and wants renewing. Names the drift; never rewrites the description — council flags, Elrond renews. Loop-neutral. |
[MELLON] |
[FRIEND] |
Elrond | Summons. Speak, friend, and enter — enrolls a planless ticket in the skeleton-stage sweeps (/glorfindel, /aule); the decider yields await_start without it. Ignored by single-ticket /council (the invocation itself is consent). |
[CEIST] |
[ASK] |
Elrond | A question put to the council. Draws a [PEDO] answer; the plan is untouched. Bare prose is read the same way — it answers, never redrafts. |
[ENVINYA] |
[ALTER] |
Elrond | Renew it. The one human word that redrafts the standing plan or skeleton. Absent it, fresh prose only draws an answer. |
[FORTH] |
[APPROVE] |
Elrond | The plan stands. Forth, Eorlingas! Council adjourns. |
[NAY] |
[REJECT] |
Elrond | The plan is abandoned. Council adjourns. |
[NAMARIE] |
[FAREWELL] |
Elrond | Farewell. Adjourn without verdict — when the thread closes for reasons other than approval or rejection (resolved out-of-band, ticket subsumed by another, etc.). |
[GWAITH] |
[FORGED], [SHIPPED] |
Celebrimbor | The Gwaith-i-Mírdain — the smith-guild of Eregion. The deed is wrought; PR/MR opened on the approved counsel. Body carries the URL and branch. Council itself never posts this; /celebrimbor does. |
[DOOM] |
[VERDICT] |
Mandos | The Doom. A verdict on whether the deed matches the decree — Covered / Missing / Scope-crept against the ticket's goal. Loop-neutral; uncounted toward the turn limit, never redrafts or approves. Council never posts it; /mandos post does. |
[METTA] |
— | Aulë | Quenya "the end." Closed on merge — the ticket's [GWAITH] PR/MR has merged; State moved to the project's closed value. Terminal; the true no-op the decider calls at_rest. Loop-neutral; uncounted toward the turn limit. Council never posts it; /aule does. |
The English aliases ([PLAN vN], [AGENT-ASK], [ANSWER], [RENEWED], [STALE], [FRIEND], [ASK], [ALTER], [APPROVE], [REJECT], [FAREWELL], [FORGED], [SHIPPED], [VERDICT]) are accepted equivalents, recognized everywhere their Tolkien primaries are. Use either form; the parser treats them identically. User-facing reports prefer the Tolkien token.
Human replies between these tokens are free-form prose — read as a question and answered with [PEDO], never folded into a redraft. Only [ENVINYA]/[ALTER] redraws the plan.
Rules
- Never act on Elrond's behalf. The skill only reads tickets and posts comments.
- The living plan comment is edited in place on a redraft (both trackers), followed by a
[VINYA]notice;[PEDO]answers,[PARLEY], and the first-turn plan creation are appends. No comment is ever deleted. - Loop-safe. If no fresh counsel from Elrond has come since the bot's last word, post nothing. Repeated invocations between Elrond's replies must be silent no-ops. The thread, not the invocation count, is the source of truth.
- Description drift is flagged, never fixed. On approval, if the accepted plan has materially diverged from the ticket description, council posts one
[ENWINA]notice naming the drift, then stops — it does not rewrite the description (Elrond's words are Elrond's to change). Once per ticket, guarded by the presence of a prior[ENWINA]; when in doubt whether the drift is material, post nothing. - If the tracker hook reports a credential is missing, surface the error and stop — do not proceed.
- Turn limit is five counsels per ticket. On the sixth, post
[PARLEY]asking to take the thread offline. (Only triggers when fresh counsel exists; otherwise the loop-safe rule keeps the thread quiet.) - Case-insensitive matching of all fourteen tokens and their aliases.
- Two trackers are wired: YouTrack and Jira. The hybrid dispatch rule above chooses between them.
- Jira tickets are real work. Do not post test or diagnostic comments to Jira during smoke testing. Use
COUNCIL_DRY_RUN=1env on the Jira comment and edit hooks (council-jira-comment.sh,jira-comment-edit.sh) for shape verification, and do write-path smoke tests against YouTrack (MET-1). - Do not surface tracker tokens in logs, responses, or saved files.