diff --git a/server/internal/daemon/execenv/runtime_config.go b/server/internal/daemon/execenv/runtime_config.go index 4895b708bf..d1b82a3bb5 100644 --- a/server/internal/daemon/execenv/runtime_config.go +++ b/server/internal/daemon/execenv/runtime_config.go @@ -475,10 +475,11 @@ func buildMetaSkillContent(provider string, ctx TaskContextForEnv) string { b.WriteString("### Core\n") b.WriteString("- `multica issue get --output json` — Get full issue details.\n") b.WriteString("- `multica issue comment list [--thread [--tail N] | --recent N] [--before --before-id ] [--since ] --output json` — List comments on an issue. Default returns the full flat timeline (server cap 2000). On busy issues prefer the thread-aware reads: `--thread ` returns one conversation (root + every reply); `--thread --tail N` caps replies to the N most recent (root is always included, even at `--tail 0`); `--recent N` returns the N most recently active threads. `--before` / `--before-id` walks older replies under `--thread --tail` (stderr label: `Next reply cursor`) or older threads under `--recent` (stderr label: `Next thread cursor`). `--since` is for incremental polling and may combine with `--thread` (with or without `--tail`) or `--recent`.\n") - b.WriteString("- `multica issue create --title \"...\" [--description \"...\" | --description-file | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id ] [--parent ] [--project ] [--due-date ] [--attachment ]` — Create a new issue; `--attachment` may be repeated. For agent-authored long descriptions, prefer `--description-file ` — flags after a HEREDOC terminator can be silently swallowed (#4182).\n") - b.WriteString("- `multica issue update [--title X] [--description X | --description-file | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id ] [--parent ] [--project ] [--due-date ]` — Update issue fields; use `--parent \"\"` to clear parent. For agent-authored long descriptions, prefer `--description-file ` over stdin (#4182).\n") + b.WriteString("- `multica issue create --title \"...\" [--description \"...\" | --description-file | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id ] [--parent ] [--stage N] [--project ] [--due-date ] [--attachment ]` — Create a new issue; `--attachment` may be repeated. `--stage N` (N ≥ 1) groups a sub-issue into an ordered barrier group under its parent so the parent wakes per stage, not per child. For agent-authored long descriptions, prefer `--description-file ` — flags after a HEREDOC terminator can be silently swallowed (#4182).\n") + b.WriteString("- `multica issue update [--title X] [--description X | --description-file | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id ] [--parent ] [--stage N] [--project ] [--due-date ]` — Update issue fields; use `--parent \"\"` to clear parent. For agent-authored long descriptions, prefer `--description-file ` over stdin (#4182).\n") b.WriteString("- `multica repo checkout [--ref ]` — Check out a repository into the working directory (creates a git worktree with a dedicated branch; use `--ref` for review/QA on a specific branch, tag, or commit)\n") b.WriteString("- `multica issue status ` — Shortcut for `issue update --status` when you only need to flip status (todo, in_progress, in_review, done, blocked, backlog, cancelled)\n") + b.WriteString("- `multica issue children [--output json]` — List a parent's sub-issues grouped by stage (table or JSON), so you can see how many children there are, which stage each is in, and which stage to promote next.\n") // Available Commands lists `multica issue comment add` with all three input // modes, but the menu entry now actively steers agents away from inlining // `--content` for agent-authored bodies. The prescriptive form-by-platform @@ -711,6 +712,7 @@ func buildMetaSkillContent(provider string, ctx TaskContextForEnv) string { if ctx.IssueID != "" && ctx.ChatSessionID == "" && ctx.QuickCreatePrompt == "" && ctx.AutopilotRunID == "" { b.WriteString("## Sub-issue Creation\n\n") b.WriteString("**Choosing `--status` when creating sub-issues.** `--status todo` = **start now** (the default — an agent assignee fires immediately). `--status backlog` = **wait** (assignee is set but no trigger fires; promote later with `multica issue status todo`). Parallel children: all `--status todo`. Strict serial Step 1→2→3: only Step 1 is `todo`; Steps 2/3 are `--status backlog` from the start, promoted in turn.\n\n") + b.WriteString("**Ordering with stages.** When sub-issues run in phases or wait on each other, group them with `--stage ` (N ≥ 1) rather than hand-promoting the backlog chain above. Children sharing a stage run together; once a whole stage finishes (every child in it terminal — `done`/`cancelled`) you are woken once to review and promote the next stage. Create the first stage's children at `--status todo` and later stages at `--stage k --status backlog`; with no `--stage` the whole sibling set behaves as one implicit stage (woken once, when the last child finishes). Reach for stages whenever a plan has more than one step or a step must wait for a group — it is the intended way to express order, and it is cheaper than tracking the chain by hand. Run `multica issue children ` to see children grouped by stage before promoting.\n\n") } if len(ctx.AgentSkills) > 0 { diff --git a/server/internal/daemon/execenv/runtime_config_test.go b/server/internal/daemon/execenv/runtime_config_test.go index 8f3207aa6e..8a2535b662 100644 --- a/server/internal/daemon/execenv/runtime_config_test.go +++ b/server/internal/daemon/execenv/runtime_config_test.go @@ -50,6 +50,12 @@ func TestSubIssueCreationSectionPresentForIssueRuns(t *testing.T) { "`multica issue status todo`", "all `--status todo`", "`--status backlog` from the start", + // Stage guidance must reach the always-on brief so agents + // reach for stages instead of only the manual backlog chain + // (MUL-3508 follow-up). + "**Ordering with stages.**", + "`--stage `", + "`multica issue children `", } { if !strings.Contains(out, want) { t.Errorf("[%s] section missing %q", tc.name, want)