@mmerterden/multi-agent-pipeline 20.11.1 → 20.13.0

package/pipeline/skills/shared/core/multi-agent-analysis/SKILL.md

@@ -15,6 +15,11 @@ Produces a stakeholder-ready, platform-agnostic feature-spec document set (one m
 
 > **Language**: Per `refs/rules.md` Language Application matrix - instruction prose stays English. `AskUserQuestion.question`, `.options[].label` and `.options[].description` follow `outputLanguage`; only `header` stays English (<=12-char chip). The emitted document body follows `outputLanguage` (`tr` or `en`).
 
+## Gotchas
+
+- Design is fetched only inside this command (Locked 29). A variant missing from the document is added by re-running analysis, never by a later phase.
+- `status: final` fails the validator while any `AS-NN` is still open; publish drafts as `draft`.
+
 ## When to use
 
 - Before kicking off a new feature: design + API + business rules + architecture plan + test strategy crystallized into one per-platform document set
@@ -40,7 +45,7 @@ One run emits one profile. A missing input never blocks either: the gap is writt
 
 The template has 23 main sections plus footer (Glossary, Changelog). The rendered set is chosen from evidence by the omission table (Locked 2), not by a mode: a section with no evidence drops, and 19 Alternatives, 22 Glossary and 18 Rollout are default-drop.
 
-**Section omission**: zero-evidence sections are dropped entirely (no "TBD" placeholder); numbering re-flows to stay sequential. Sections 1, 2, 4, 9, 13, 14, 20, 21 are never omitted.
+**Section omission**: zero-evidence sections are dropped entirely (no "TBD" placeholder); a rendered section keeps its canonical template number, so the rendered set has gaps. Sections 1, 2, 4, 9, 13, 14, 20, 21 are never omitted.
 
 **Two-pass render**: Pass A computes the shared logical content once; Pass B projects it onto each selected platform using conventions extracted from the repos (Phase 1c, seven pattern groups with confidence levels). Every projected cell carries an evidence footnote. A convention preview gate lets the user approve or override cells before any file renders.
 

package/pipeline/skills/shared/core/multi-agent-analysis-jira/SKILL.md

@@ -2,7 +2,7 @@
 name: multi-agent-analysis-jira
 description: "Turn a rendered analysis document into a Jira story tree: derive stories from the document's own rule ids, check coverage both ways, preview every byte, then create only what does not already exist. Use when an analysis is final and the work needs tickets."
 user-invocable: true
-argument-hint: "[analysis.md] [--project KEY]  -  optional; with no argument, pick from the documents this run emitted"
+argument-hint: "[analysis.md] [--project KEY] [--epic KEY]  -  optional; with no argument, pick from the documents this run emitted"
 metadata:
   language: en
   not-for: create-jira, jira
@@ -18,13 +18,26 @@ invents a story: every node comes from an id the document defines.
 Contract, severities and reasoning:
 `$HOME/.claude/multi-agent-refs/features/analysis-jira.md`.
 
+## Gotchas
+
+- An issue whose label already exists is skipped, never updated. Editing the document and re-running creates only what is missing; existing tickets keep their old text.
+- A document with no `BR-`/`FG-` ids still plans, from its `4.N` sub-sections, but its coverage verdict is `unverifiable`: there is nothing to check the tree against.
+- An open `EKLENECEK`/`TBD` marker or an open Section 20 row stops planning with exit 4. Resolve them with `/multi-agent-analysis-resolve` first.
+- The epic must already exist: stories are linked to it, never an epic created. On Server/Data Center the Epic Link field is discovered from the site; when none is found the stories are created unlinked and the writer says so.
+- Channel clones (`issueTree.cloneByChannel`) carry their own labels and are searched like stories, so a re-run never doubles them or their links.
+- Story bodies hold only document text. A body warning (no user story, fewer than 2 criteria, no negative criterion) is a gap in the document; fix the document, not the ticket.
+
 ## Phase 1 - Plan, offline
 
 ```bash
-node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json > /tmp/ma-plan.json
-node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>"
+node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json $PAGE > /tmp/ma-plan.json
+node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" $PAGE
 ```
 
+`$PAGE` is `--page-url <url>` when the document was published (the run's
+`outputs.confluencePages[]`); without it the front-matter `confluence_url` is
+used, and with neither the story bodies carry no analysis link.
+
 Exit 4 means the document still carries an open placeholder. Stop and report it:
 the step is `/multi-agent:analysis-resolve`, and a tree built from an open
 question publishes the gap as work somebody is now assigned.
@@ -48,12 +61,19 @@ what makes a preview meaningful:
 - every field beside the pref key it came from, so a wrong setting shows here
   rather than in Jira afterwards
 - the write count
+- every story's full description, as it will be written, with its body
+  warnings; `--brief` gives the one-line-per-node view
+
+Then ask for the epic, once. `AskUserQuestion`:
+
+- **Link to an existing epic** - the user types its key (`--epic <KEY>`)
+- **No epic** - the stories are created unlinked
 
 Then the dry run, which is what proves the writer agrees with the plan:
 
 ```bash
 bash "$HOME/.claude/lib/analysis-jira-write.sh" \
-  --plan /tmp/ma-plan.json --project "<KEY>" --dry-run
+  --plan /tmp/ma-plan.json --project "<KEY>" [--epic "<EPIC>"] --dry-run
 ```
 
 ## Phase 3 - Approve
@@ -79,11 +99,14 @@ be reachable.
 invented id means the plan cites something the document does not define - treat
 that as a defect in the plan, not a warning to click past.
 
+Body warnings are printed before the question too. They do not block: the
+ticket says only what the document says, and the warning names the gap.
+
 ## Phase 4 - Write
 
 ```bash
 bash "$HOME/.claude/lib/analysis-jira-write.sh" \
-  --plan /tmp/ma-plan.json --project "<KEY>"
+  --plan /tmp/ma-plan.json --project "<KEY>" [--epic "<EPIC>"]
 ```
 
 It searches by label first and skips what exists. Re-running is safe and is the
@@ -93,9 +116,36 @@ findable rather than duplicable.
 **Never pass `--force`-like flags, and never update an existing node.** Jira has
 no backup path for fields other than description.
 
+### Write the tickets back
+
+The document lists what it produced. Local and idempotent: the table sits
+between `<!-- tickets:start -->` and `<!-- tickets:end -->`, a re-run replaces
+it, and only nodes with a key appear.
+
+```bash
+LEDGER="$HOME/.claude/logs/multi-agent/_analysis-jira/$(jq -r '.document.id // "unidentified"' /tmp/ma-plan.json).jsonl"
+node "$HOME/.claude/scripts/analysis-tickets-writeback.mjs" \
+  --doc "<analysis.md>" --ledger "$LEDGER" --plan /tmp/ma-plan.json
+```
+
+When the document has a Confluence page, updating it is a **separate**
+`AskUserQuestion`, never part of the tree approval:
+
+- **Update the Confluence page** - publish the document with its new table
+- **Keep it local** - the page stays as it is
+
+```bash
+python3 "$HOME/.claude/lib/md2confluence-v3.py" update \
+  --page-id "<pageId>" --title "<page title>" \
+  --markdown "<analysis.md>" --attachments-dir "$(dirname "<analysis.md>")"
+```
+
+Read its JSON envelope as the analysis render step does, and surface any
+missing-attachment warning.
+
 ## Phase 5 - Report
 
-Keys created, keys skipped, the coverage verdict, and the ledger path. If the
+Keys created, keys skipped, the epic linked (or none), the coverage verdict, and the ledger path. If the
 verdict was `unverifiable`, say that in the report too - not only at approval
 time, because the report is what gets pasted elsewhere.
 

package/pipeline/skills/shared/core/multi-agent-autopilot/SKILL.md

@@ -13,6 +13,12 @@ metadata:
 
 Run the task end-to-end with no confirmations.
 
+## Gotchas
+
+- The guard decides within a 5-second internal deadline and fails closed when unattended. On a heavily loaded machine a correct command can be refused for time, not for policy.
+- An unattended run never pushes or opens a PR itself: it records the request in `pr-request.json` and the runner publishes it.
+- An unattended run cannot run `/multi-agent-stack` or write `.claude/` in the repo; a missing stack toolkit is read from a local marketplace clone instead.
+
 ## What changes
 
 | Phase | Normal | Autopilot |

package/pipeline/skills/shared/core/multi-agent-doctor/SKILL.md

@@ -20,6 +20,12 @@ same way - late, mid-run, after the pickers had been answered. A missing script
 fails at the call. Malformed preferences fail after Phase 0 has asked five
 questions. A token in a remote URL does not fail at all; it leaks.
 
+## Gotchas
+
+- Exit 4 means the layout did not resolve and nothing was checked. It is not a pass.
+- Without `--probe` no credential is sent anywhere, so a revoked token still reads as mapped.
+- `usage-report` SKIP means nothing has been sent from this machine yet, not that reporting works.
+
 ## Run it
 
 ```bash

package/pipeline/skills/shared/core/multi-agent-review/SKILL.md

@@ -13,6 +13,11 @@ metadata:
 
 Skip Phase 0-3 and review a diff only. Input shapes: a PR (`#N`, `repo#N`, GitHub/Bitbucket-Server PR URL), a branch name, or empty.
 
+## Gotchas
+
+- The counterpart-repo comparison needs exactly one resolved candidate. With several, an unattended run skips it silently, so an autopilot review can have no cross-platform section.
+- The counterpart's stack comes from marker files, never from the repo name.
+
 ## Steps
 
 1. **Resolve the input** (`{kind, provider}`):

package/pipeline/skills/shared/core/multi-agent-review-analysis/SKILL.md

@@ -13,6 +13,11 @@ metadata:
 
 `multi-agent-review` judges a diff. This judges the document that diff was supposed to come from, before the code exists. No worktree, no branch, no commit, and the reviewed document is never edited in place.
 
+## Gotchas
+
+- Validator ERRORs are Blockers and WARNs are Important, unless the document states why the warned-about item is acceptable.
+- Every rubric class is printed, with `none` when empty. A class missing from the verdict did not run; it is not a clean result.
+
 ## Flow
 
 Read `$HOME/.copilot/multi-agent-refs/analysis/review.md` and execute it:

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: multi-agent-setup
 description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up for the first time, or tokens and git identity need onboarding."
+argument-hint: "[jira-keys | hosts | accounts]  -  optional; no argument runs the whole onboarding"
 user-invocable: true
 metadata:
   language: en