devops-bot-sdk 1.7.6__tar.gz → 1.7.20__tar.gz

{devops_bot_sdk-1.7.6 → devops_bot_sdk-1.7.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.7.6
+Version: 1.7.20
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.7.6 → devops_bot_sdk-1.7.20}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.7.6
+Version: 1.7.20
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.7.6 → devops_bot_sdk-1.7.20}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ sdk/departments.py
 sdk/estimator.py
 sdk/exceptions.py
 sdk/fallback_handoff.py
+sdk/faqs.py
 sdk/firewall.py
 sdk/formats.py
 sdk/git_ops.py
@@ -31,6 +32,7 @@ sdk/graphify.py
 sdk/help_actions.py
 sdk/helpdesk.py
 sdk/helpdesk_kb.md
+sdk/instructions_template.py
 sdk/intake.py
 sdk/journal.py
 sdk/local_exec.py
@@ -49,6 +51,7 @@ sdk/router.py
 sdk/run_auto.py
 sdk/schedule_tickets.py
 sdk/scheduler.py
+sdk/scope_plan.py
 sdk/self_report.py
 sdk/self_report_local.py
 sdk/sse.py
@@ -58,7 +61,10 @@ sdk/task_types.py
 sdk/test.py
 sdk/test_pipeline.py
 sdk/ticket_board.py
+sdk/ticket_bulk.py
 sdk/ticket_fields.py
+sdk/ticket_plan.py
+sdk/ticket_pools.py
 sdk/tickets.py
 sdk/updater.py
 sdk/url_access.py
@@ -144,6 +150,7 @@ sdk/ui/static/app.js
 sdk/ui/static/chat.html
 sdk/ui/static/custom-agents.html
 sdk/ui/static/default-agents.html
+sdk/ui/static/faqs.html
 sdk/ui/static/help.html
 sdk/ui/static/index.html
 sdk/ui/static/report.html
@@ -193,6 +200,7 @@ tests/test_epic_session_isolation.py
 tests/test_estimator.py
 tests/test_fallback_cli.py
 tests/test_fallback_cli_upgrade.py
+tests/test_faqs.py
 tests/test_firewall_open_on_update.py
 tests/test_formats.py
 tests/test_git_action.py
@@ -207,6 +215,7 @@ tests/test_help_attachments.py
 tests/test_help_questions.py
 tests/test_helpdesk.py
 tests/test_infographic_data.py
+tests/test_instructions_template.py
 tests/test_intake_job_outcome.py
 tests/test_intake_plan_review.py
 tests/test_journal.py
@@ -245,8 +254,11 @@ tests/test_swagger_command.py
 tests/test_task_file_and_plan_run.py
 tests/test_task_file_format_doc.py
 tests/test_ticket_board.py
+tests/test_ticket_bulk.py
 tests/test_ticket_cli.py
 tests/test_ticket_fields.py
+tests/test_ticket_plan.py
+tests/test_ticket_pools.py
 tests/test_ticket_run_resolve_by_id.py
 tests/test_ticket_schedule_and_agent.py
 tests/test_ticket_speed_fixes.py

{devops_bot_sdk-1.7.6 → devops_bot_sdk-1.7.20}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.7.6
+Version: 1.7.20
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.7.6"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.7.20"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.7.6 → devops_bot_sdk-1.7.20}/sdk/cli.py

@@ -202,6 +202,9 @@ def main() -> None:
     if noun == "tickets":
         _ticket_list(rest)
         return
+    if noun == "pool" or noun == "pools":
+        _pool_command(rest)
+        return
 
     if noun == "agentd":
         _agentd_command(rest)
@@ -267,6 +270,7 @@ def _print_usage() -> None:
     print("  agentos agent <set-key NAME KEY[=VALUE]…|keys NAME|rm-key NAME KEY…>   # persistent API keys (custom agents)")
     print("  agentos ticket <list|create|update KEY_OR_ID|delete KEY_OR_ID|help>")
     print("  agentos tickets [--status S] [--project KEY] [--all] [--json]   # how many To Do / In Progress / … and which")
+    print("  agentos pool <list|show|create|add|remove|move|order|set|run|delete|help>   # ticket pools: up to 50 tickets run together, in order")
     print("  agentos integration <add PATH|test NAME|list|rm NAME>")
     print("  agentos default-agents list [--department-id UUID]   # read-only; agents are created in the web app")
     print("  agentos agentd <start [--foreground]|status>")
@@ -1203,6 +1207,20 @@ def _ticket_usage() -> None:
     print("      [--instructions TEXT | --instructions-file PATH] [--priority P] [--status S]")
     print("      [--points N] [--assignee EMAIL] [--type TYPE]")
     print("  agentos ticket show KEY_OR_ID [--json]    # summary, status, description, humanInstructions")
+    print("  agentos ticket bulk-update KEY… | --pool NAME  [--status S] [--priority P] [--type T] [--points N]")
+    print("      [--assignee EMAIL] [--description TEXT|--description-file PATH] [--instructions TEXT|--instructions-file PATH]")
+    print("      [--description-mode M] [--instructions-mode M] [--clear-description] [--clear-instructions]")
+    print("      # one or a few fields on up to 50 tickets; M: append (default) | prepend | replace")
+    print("  agentos ticket instructions KEY… | --pool NAME  (--text TEXT | --file PATH)")
+    print("      [--replace | --prepend | --clear]    # Human Instructions on up to 50 tickets at once (default: append)")
+    print("  agentos ticket bulk-create PLAN.md|PLAN.json [--project KEY] [--instructions TEXT | --instructions-file PATH]")
+    print("      [--type T] [--priority P] [--pool NAME | --module-pools] [--dry-run] [--example]")
+    print("      # many tickets from one plan: modules, cross-module, Epics → Stories, Tasks, Bugs")
+    print("  agentos ticket placeholders [--template KIND]   # {ticket_key} {summary} {slug}… filled per ticket; KIND: development|content|research|design|general")
+    print("  agentos ticket gen-instructions [KEY… | --pool NAME] [--kind KIND] [--notes TEXT] [--from-file PATH] [-o FILE]")
+    print("      # the AI writes Human Instructions for any kind of work (picks it, or --kind), using the placeholders")
+    print("  agentos ticket scope-to-plan SCOPE.md [--project KEY] [--modules \"A, B\"] [-o PLAN.md]")
+    print("      # the AI drafts that plan from a detailed scope document (nothing is created)")
     print("  agentos ticket delete KEY_OR_ID [--yes]   # asks to confirm unless --yes")
     print()
     print("  TYPE: Epic|Story|Task|Bug|Sub-task (default Task)   P: Lowest|Low|Medium|High|Highest (default Medium)")
@@ -1242,6 +1260,500 @@ def _parse_ticket_flags(args: list[str], *, creating: bool) -> dict[str, str]:
     return fields
 
 
+_POOL_USAGE = """usage: agentos pool <command>   — up to 50 tickets you run together, in your order
+
+  agentos pool list                                   # every pool, its size and last run
+  agentos pool show NAME                              # run order, each ticket's summary/status, instructions
+  agentos pool create NAME KEY… [--instructions TEXT] [--parallel N]   # new pool (keys in run order)
+  agentos pool add NAME KEY… [--at POS]               # add tickets (at the end, or at position POS)
+  agentos pool remove NAME KEY…                       # take tickets out
+  agentos pool move NAME KEY POS                      # move one ticket to position POS (1 = first)
+  agentos pool order NAME KEY…                        # these first, in this order; the rest follow
+  agentos pool set NAME [--instructions TEXT | --clear-instructions] [--parallel N] [--rename NEW]
+  agentos pool run NAME [--parallel N]                # run it now (= agentos-auto pool NAME)
+  agentos pool delete NAME                            # remove the pool (tickets are untouched)
+
+  --instructions: applies to EVERY ticket in the pool, ahead of each ticket's own
+  Human Instructions. --parallel: tickets at once, 1–8 (default 3) — never two on
+  the same repo, so same-repo tickets still run in your order.
+"""
+
+
+def _pool_opts(args: list[str], valued: tuple[str, ...], bare: tuple[str, ...] = ()) -> tuple[list[str], dict]:
+    """Split ``args`` into positionals and ``{flag: value}`` (bare flags → True)."""
+    pos: list[str] = []
+    opts: dict = {}
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in valued:
+            if i + 1 >= len(args):
+                print(f"error: expected a value after {a}")
+                sys.exit(1)
+            opts[a] = args[i + 1]
+            i += 2
+            continue
+        if a in bare:
+            opts[a] = True
+        elif a.startswith("--"):
+            print(f"error: unknown option {a} — see --help")
+            sys.exit(1)
+        else:
+            pos.append(a)
+        i += 1
+    return pos, opts
+
+
+def _pool_print(pool: dict, info: dict | None = None) -> None:
+    from sdk import log_colors
+    paint = log_colors.colorize if log_colors.enabled() else (lambda x: x)
+    print(f"pool {pool['name']} — {len(pool['keys'])} ticket(s), up to {pool.get('parallel')} at once"
+          + (f", last run {pool['last_run_at']}" if pool.get("last_run_at") else ""))
+    width = max(len(k) for k in pool["keys"]) if pool["keys"] else 0
+    for n, k in enumerate(pool["keys"], 1):
+        row = (info or {}).get(k)
+        tail = f"  {row['summary'][:70]}  → {row['status']}" if row else ("  (not found on the board)" if info else "")
+        print(paint(f"  {n:>2}. {k.ljust(width)}{tail}"))
+    if pool.get("instructions"):
+        print("  instructions (every ticket):")
+        for line in pool["instructions"].splitlines():
+            print(f"    {line}")
+
+
+def _pool_command(args: list[str]) -> None:
+    """`agentos pool …` — ticket pools (sdk/ticket_pools.py)."""
+    from sdk import ticket_pools as TP
+
+    sub, rest = (args[0], args[1:]) if args else ("list", [])
+    if sub in ("-h", "--help", "help"):
+        print(_POOL_USAGE, end="")
+        return
+
+    def _parallel(opts: dict) -> int | None:
+        return int(opts["--parallel"]) if str(opts.get("--parallel", "")).isdigit() else (
+            None if "--parallel" not in opts else -1)
+
+    try:
+        if sub in ("list", "ls"):
+            pools = TP.list_pools()
+            if not pools:
+                print("no pools yet — `agentos pool create NAME KEY… [--instructions TEXT]`")
+                return
+            for p in pools:
+                print(f"  {p['name']:<24} {len(p['keys']):>2} ticket(s)  ×{p.get('parallel')}"
+                      f"  {'instructions' if p.get('instructions') else '':<12}"
+                      f"  {('last run ' + p['last_run_at']) if p.get('last_run_at') else 'never run'}")
+            return
+        if sub == "show":
+            if not rest:
+                print("usage: agentos pool show NAME")
+                sys.exit(1)
+            pool = TP.get(" ".join(rest))
+            info = None
+            try:
+                from sdk.client import BackendClient
+                info = asyncio.run(TP.describe(BackendClient.from_config(), pool["keys"])) or None
+            except Exception:  # noqa: BLE001 — no token / no backend: show the keys alone
+                info = None
+            _pool_print(pool, info)
+            return
+        if sub == "create":
+            pos, opts = _pool_opts(rest, ("--instructions", "--parallel"))
+            if len(pos) < 2:
+                print("usage: agentos pool create NAME KEY… [--instructions TEXT] [--parallel N]")
+                sys.exit(1)
+            pool = TP.create(pos[0], pos[1:], opts.get("--instructions", ""), _parallel(opts))
+            shown = f'"{pool["name"]}"' if " " in pool["name"] else pool["name"]
+            print(f"✓ created pool {pool['name']} with {len(pool['keys'])} ticket(s) — "
+                  f"run it: agentos pool run {shown}")
+            return
+        if sub == "add":
+            pos, opts = _pool_opts(rest, ("--at",))
+            if len(pos) < 2:
+                print("usage: agentos pool add NAME KEY… [--at POS]")
+                sys.exit(1)
+            pool = TP.add(pos[0], pos[1:], int(opts["--at"]) if "--at" in opts else None)
+        elif sub in ("remove", "rm"):
+            if len(rest) < 2:
+                print("usage: agentos pool remove NAME KEY…")
+                sys.exit(1)
+            pool = TP.remove(rest[0], rest[1:])
+        elif sub == "move":
+            if len(rest) != 3 or not rest[2].isdigit():
+                print("usage: agentos pool move NAME KEY POS")
+                sys.exit(1)
+            pool = TP.move(rest[0], rest[1], int(rest[2]))
+        elif sub == "order":
+            if len(rest) < 2:
+                print("usage: agentos pool order NAME KEY…")
+                sys.exit(1)
+            pool = TP.order(rest[0], rest[1:])
+        elif sub == "set":
+            pos, opts = _pool_opts(rest, ("--instructions", "--parallel", "--rename"),
+                                   ("--clear-instructions",))
+            if len(pos) != 1 or not opts:
+                print("usage: agentos pool set NAME [--instructions TEXT | --clear-instructions] "
+                      "[--parallel N] [--rename NEW]")
+                sys.exit(1)
+            instr = "" if opts.get("--clear-instructions") else opts.get("--instructions")
+            pool = TP.update(pos[0], instructions=instr, parallel=_parallel(opts),
+                             rename=opts.get("--rename"))
+        elif sub == "delete":
+            if not rest:
+                print("usage: agentos pool delete NAME")
+                sys.exit(1)
+            pool = TP.delete(" ".join(rest))
+            print(f"✓ deleted pool {pool['name']} (its {len(pool['keys'])} tickets are untouched)")
+            return
+        elif sub == "run":
+            pos, opts = _pool_opts(rest, ("--parallel", "--workspace-root"), ("--foreground", "-f"))
+            if not pos:
+                print("usage: agentos pool run NAME [--parallel N]")
+                sys.exit(1)
+            from sdk import run_auto
+            argv = ["agentos-auto", "pool", " ".join(pos)]
+            for f in ("--parallel", "--workspace-root"):
+                if f in opts:
+                    argv += [f, opts[f]]
+            argv += [f for f in ("--foreground", "-f") if opts.get(f)]
+            sys.argv = argv
+            run_auto.main()
+            return
+        else:
+            print(f"unknown pool command {sub!r}\n")
+            print(_POOL_USAGE, end="")
+            sys.exit(1)
+    except TP.PoolError as exc:
+        print(f"error: {exc}")
+        sys.exit(1)
+    _pool_print(pool)
+
+
+def _read_text_arg(opts: dict, text_flag: str, file_flag: str) -> str | None:
+    """--text / --file twins; exits 1 on both or an unreadable file."""
+    if text_flag in opts and file_flag in opts:
+        print(f"error: pass {text_flag} or {file_flag}, not both")
+        sys.exit(1)
+    if file_flag in opts:
+        try:
+            return Path(opts[file_flag]).expanduser().read_text(encoding="utf-8")
+        except OSError as exc:
+            print(f"error: cannot read {opts[file_flag]}: {exc}")
+            sys.exit(1)
+    return opts.get(text_flag)
+
+
+def _ticket_bulk_instructions(args: list[str]) -> None:
+    """`agentos ticket instructions KEY… (--text T | --file P) [--replace|--prepend|--clear]`."""
+    from sdk import ticket_bulk
+    from sdk.client import BackendClient
+
+    if not args or args[0] in ("-h", "--help", "help"):
+        print("usage: agentos ticket instructions KEY… | --pool NAME  (--text TEXT | --file PATH)")
+        print("         [--replace | --prepend | --clear]")
+        print("  Writes Human Instructions on every ticket given (at most 50). Default: APPEND to")
+        print("  what each ticket already has (a block it already contains is not added twice).")
+        sys.exit(0 if args else 1)
+    keys, opts = _pool_opts(args, ("--text", "--file", "--pool"), ("--replace", "--prepend", "--clear", "--append"))
+    modes = [m for m in ("replace", "prepend", "clear", "append") if opts.get("--" + m)]
+    if len(modes) > 1:
+        print("error: choose one of --append, --prepend, --replace, --clear")
+        sys.exit(1)
+    mode = modes[0] if modes else "append"
+    text = _read_text_arg(opts, "--text", "--file") or ""
+    if mode != "clear" and not text.strip():
+        print("error: give the instructions with --text TEXT or --file PATH (or --clear)")
+        sys.exit(1)
+    keys = _bulk_keys(keys, opts.get("--pool"))
+    res = asyncio.run(ticket_bulk.set_instructions(BackendClient.from_config(), keys, text, mode))
+    if "updated" not in res:
+        print(f"error: {res['error']}")
+        sys.exit(1)
+    verb = {"append": "appended to", "prepend": "prepended to", "replace": "replaced on",
+            "clear": "cleared on"}[mode]
+    _print_bulk_result(res, f"instructions {verb}")
+    sys.exit(0 if res["ok"] else 1)
+
+
+def _bulk_keys(keys: list[str], pool: str | None) -> list[str]:
+    from sdk import ticket_pools
+    if pool:
+        try:
+            keys = keys + [k for k in ticket_pools.get(pool)["keys"] if k not in keys]
+        except ticket_pools.PoolError as exc:
+            print(f"error: {exc}")
+            sys.exit(1)
+    if not keys:
+        print("error: which tickets? — give keys, or --pool NAME")
+        sys.exit(1)
+    return keys
+
+
+def _print_bulk_result(res: dict, verb: str) -> None:
+    if res["updated"]:
+        print(f"✓ {verb} {len(res['updated'])} ticket(s): {', '.join(res['updated'])}")
+    if res["unchanged"]:
+        print(f"  unchanged (already had it): {', '.join(res['unchanged'])}")
+    for p in res.get("partial") or []:
+        print(f"⚠ {p['key']}: the backend accepted but did NOT apply {', '.join(p['not_applied'])}")
+    for f in res["failed"]:
+        print(f"✗ {f['key']}: {f['error']}")
+
+
+def _ticket_bulk_update(args: list[str]) -> None:
+    """`agentos ticket bulk-update KEY…|--pool NAME --status S --priority P …`."""
+    from sdk import ticket_bulk
+    from sdk.client import BackendClient
+
+    if not args or args[0] in ("-h", "--help", "help"):
+        print("usage: agentos ticket bulk-update KEY… | --pool NAME  [one or more fields]")
+        print("  --status S  --priority P  --type T  --points N  --assignee EMAIL")
+        print("  --description TEXT | --description-file PATH   [--description-mode append|prepend|replace]")
+        print("  --instructions TEXT | --instructions-file PATH [--instructions-mode append|prepend|replace]")
+        print("  --clear-description  --clear-instructions")
+        print("  The same change on every ticket given (at most 50); tickets that already match are")
+        print("  left alone. Text fields APPEND by default.")
+        sys.exit(0 if args else 1)
+    valued = ("--pool", "--status", "--priority", "--type", "--points", "--assignee", "--description",
+              "--description-file", "--instructions", "--instructions-file", "--description-mode",
+              "--instructions-mode")
+    keys, opts = _pool_opts(args, valued, ("--clear-description", "--clear-instructions"))
+    keys = _bulk_keys(keys, opts.get("--pool"))
+    fields: dict = {k: opts[f] for f, k in (("--status", "status"), ("--priority", "priority"),
+                                            ("--type", "type"), ("--points", "points"),
+                                            ("--assignee", "assigneeEmail")) if f in opts}
+    modes: dict = {}
+    for name, wire in (("description", "description"), ("instructions", "humanInstructions")):
+        text = _read_text_arg(opts, f"--{name}", f"--{name}-file")
+        if opts.get(f"--clear-{name}"):
+            if text is not None:
+                print(f"error: --clear-{name} and --{name} together make no sense")
+                sys.exit(1)
+            modes[wire] = "clear"
+        elif text is not None:
+            fields[wire] = text
+            modes[wire] = opts.get(f"--{name}-mode", "append")
+            if modes[wire] == "clear":
+                print(f"error: use --clear-{name} to clear it")
+                sys.exit(1)
+    if not fields and not modes:
+        print("error: nothing to update — pass at least one field (see --help)")
+        sys.exit(1)
+    res = asyncio.run(ticket_bulk.update_many(BackendClient.from_config(), keys, fields, modes))
+    if "updated" not in res:
+        print(f"error: {res['error']}")
+        sys.exit(1)
+    _print_bulk_result(res, "updated " + ", ".join(res["fields"]) + " on")
+    sys.exit(0 if res["ok"] else 1)
+
+
+def _pname(name: str) -> str:
+    return f'"{name}"' if " " in name else name
+
+
+def _print_plan_tree(res: dict) -> None:
+    """Dry-run view: modules → Epics → Stories, with types, statuses and instructions."""
+    rows = res["tickets"]
+    c = res.get("counts") or {}
+    print(f"would create {len(rows)} ticket(s) in {res['project']}: {c.get('epic', 0)} epic(s), "
+          f"{c.get('story', 0)} story/child ticket(s), {c.get('ticket', 0)} standalone")
+    current = object()
+    for i, t in enumerate(rows):
+        if t["module"] != current:
+            current = t["module"]
+            m = next((x for x in res.get("modules") or [] if x["name"] == current), None)
+            print(f"\n{current or '(no module)'}" + (" — instructions: " + m["instructions"].splitlines()[0][:70]
+                                                   if m and m.get("instructions") else ""))
+        indent = "      " if t["parent"] is not None else "  "
+        kind = t.get("type") or "Task"
+        extra = [x for x in (t.get("priority"), f"{t['points']} pts" if t.get("points") else "",
+                             f"→ {t['status']}" if t.get("status") else "") if x]
+        note = f"  ({t['children']} children; set Done so the loop won't re-decompose it)" if t["kind"] == "epic" and t["children"] \
+            else "  (no children: the loop will decompose it)" if t["kind"] == "epic" else ""
+        print(f"{indent}{i + 1:>3}. {kind:<8} {t['summary']}" + (f"  [{' · '.join(extra)}]" if extra else "") + note)
+    for w in res.get("warnings") or []:
+        print(f"warning: {w}")
+    for p in res.get("pools") or []:
+        print(f"pool {p['name']}: {p['count']} ticket(s)")
+
+
+def _ticket_bulk_create(args: list[str]) -> None:
+    """`agentos ticket bulk-create PLAN [--project KEY] [--instructions …] [--pool NAME|--module-pools] [--dry-run]`."""
+    from sdk import ticket_plan
+
+    if args and args[0] == "--example":
+        print(ticket_plan.EXAMPLE_PLAN, end="")
+        return
+    if not args or args[0] in ("-h", "--help", "help"):
+        print("usage: agentos ticket bulk-create PLAN.md|PLAN.json [--project KEY]")
+        print("         [--instructions TEXT | --instructions-file PATH] [--type T] [--priority P]")
+        print("         [--pool NAME] [--module-pools [--pool-prefix TEXT]] [--no-module-prefix] [--dry-run]")
+        print("  Sections: `# Module: NAME` (its Instructions: apply to its tickets — e.g. the repo),")
+        print("  `# Cross-module: A, B` (inherits every named module's instructions), `## Epic: T` with")
+        print("  `### Story: T` children, standalone `## Task:` / `## Bug:`. Simple plans: one ticket per `## Summary`.")
+        print("  An Epic created with children is set Done (the loop won't decompose it again).")
+        print(f"  At most {ticket_plan.MAX_PLAN} tickets. --pool: one pool of every runnable ticket; --module-pools:")
+        print("  one pool per module (+ cross-module). Summaries get a [Module] prefix unless --no-module-prefix.")
+        print("  Example: agentos ticket bulk-create --example > plan.md   From a scope document: agentos ticket scope-to-plan")
+        sys.exit(0 if args else 1)
+    pos, opts = _pool_opts(args, ("--project", "--instructions", "--instructions-file", "--type",
+                                  "--priority", "--pool", "--pool-prefix"),
+                           ("--dry-run", "--yes", "--module-pools", "--no-module-prefix"))
+    if len(pos) != 1:
+        print("error: give exactly one plan file (use - to read stdin)")
+        sys.exit(1)
+    try:
+        text = sys.stdin.read() if pos[0] == "-" else Path(pos[0]).expanduser().read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"error: cannot read {pos[0]}: {exc}")
+        sys.exit(1)
+    shared = _read_text_arg(opts, "--instructions", "--instructions-file") or ""
+    defaults = {k: opts[f] for f, k in (("--type", "type"), ("--priority", "priority")) if opts.get(f)}
+
+    from sdk.client import BackendClient
+    client = BackendClient.from_config() if not opts.get("--dry-run") else None
+    res = asyncio.run(ticket_plan.create_from_plan(
+        client, text, project=opts.get("--project", ""), instructions=shared, defaults=defaults,
+        pool=opts.get("--pool", ""), module_pools=bool(opts.get("--module-pools")),
+        pool_prefix=opts.get("--pool-prefix", ""), module_prefix=not opts.get("--no-module-prefix"),
+        dry_run=bool(opts.get("--dry-run"))))
+    if res.get("errors") or ("created" not in res and not res.get("dry_run")):
+        for e in res.get("errors") or [res.get("error", "failed")]:
+            print(f"error: {e}")
+        sys.exit(1)
+    if res.get("dry_run"):
+        _print_plan_tree(res)
+        print("nothing created (--dry-run).")
+        return
+    for c in res["created"]:
+        under = (f"  (parent {c['parent_key']} named in its description — not linked)" if c.get("parent_unlinked")
+                 else f"  (under {c['parent_key']})" if c.get("parent_key") else "")
+        print(f"✓ {c['key'] or c['id']}  {c['summary']}{under}")
+    for n in res.get("notes") or []:
+        print(f"note: {n}")
+    for f in res["failed"]:
+        print(f"✗ {f['summary']}: {f['error']}")
+    for p in res.get("pools") or []:
+        print(f"✓ pool {p['name']} — {len(p['keys'])} ticket(s), in plan order (run it: agentos pool run {_pname(p['name'])})")
+    for e in res.get("pool_errors") or []:
+        print(f"warning: pool not created: {e}")
+    sys.exit(0 if res["ok"] else 1)
+
+
+def _ticket_placeholders(args: list[str]) -> None:
+    """`agentos ticket placeholders [--template]`."""
+    from sdk import instructions_template as itpl
+    if "--template" in args:
+        rest = [a for a in args if a != "--template"]
+        kind = (rest[0] if rest else "development").lower()
+        if kind not in itpl.TEMPLATES:
+            print(f"error: kind must be one of {', '.join(itpl.TEMPLATES)}")
+            sys.exit(1)
+        print(itpl.TEMPLATES[kind][1], end="")
+        return
+    print("Placeholders in Human Instructions — written once, filled for each ticket:")
+    for n, d in itpl.PLACEHOLDERS.items():
+        print(f"  {{{n}}}".ljust(18) + d)
+    print("  ({{name}} works too; other braces are left alone. Filled on ticket create/update,")
+    print("   bulk-update, instructions, bulk-create and at pool run time.)")
+    print("Standard formats with placeholders — for every kind of work, not only code:")
+    for k, (label, _) in itpl.TEMPLATES.items():
+        print(f"  agentos ticket placeholders --template {k}".ljust(58) + f"# {label}")
+    print("({branch} is for code work; content, research, design and general tasks use an Output Location folder.)")
+
+
+def _ticket_gen_instructions(args: list[str]) -> None:
+    """`agentos ticket gen-instructions [KEY…|--pool NAME] [--notes T] [--from-file P] [-o FILE]`."""
+    from sdk import instructions_template as itpl
+    if args and args[0] in ("-h", "--help", "help"):
+        print("usage: agentos ticket gen-instructions [KEY… | --pool NAME] [--kind KIND] [--notes TEXT] [--from-file PATH] [-o FILE]")
+        print("  The local AI writes Human Instructions for these tickets — development, content,")
+        print("  research, design or general work (it picks from the tickets, or --kind) — using")
+        print("  placeholders ({ticket_key}, {summary}, {slug}…) so ONE text fits them all.")
+        print("  --from-file: improve existing instructions. Apply with:")
+        print("    agentos ticket instructions KEY… --file OUT --replace")
+        return
+    keys, opts = _pool_opts(args, ("--notes", "--from-file", "--pool", "--kind", "-o", "--output"), ())
+    kind = (opts.get("--kind") or "auto").lower()
+    if kind != "auto" and kind not in itpl.TEMPLATES:
+        print(f"error: --kind must be auto or one of {', '.join(itpl.TEMPLATES)}")
+        sys.exit(1)
+    keys = [k.upper() for k in keys]
+    if opts.get("--pool"):
+        keys = _bulk_keys(keys, opts["--pool"])
+    existing = _read_text_arg(opts, "--existing", "--from-file") or ""
+    rows: list[dict] = []
+    if keys:
+        from sdk.client import BackendClient
+        recs = asyncio.run(BackendClient.from_config().list_tasks_by_keys(keys)) or []
+        by = {str(r.get("jiraIssueKey") or "").upper(): r for r in recs}
+        rows = [{"key": k, "summary": str(by.get(k, {}).get("summary") or ""),
+                 "description": str(by.get(k, {}).get("description") or "")} for k in keys]
+    print("generating with the local AI…", flush=True)
+    res = asyncio.run(itpl.generate(tickets=rows, notes=opts.get("--notes", ""), existing=existing, kind=kind))
+    if not res.get("ok"):
+        print(f"error: {res.get('error')}")
+        sys.exit(1)
+    out = opts.get("-o") or opts.get("--output")
+    if out:
+        Path(out).expanduser().write_text(res["instructions"], encoding="utf-8")
+        print(f"✓ written to {out}")
+        if keys:
+            print(f"apply: agentos ticket instructions {' '.join(keys)} --file {out} --replace")
+    else:
+        print(res["instructions"], end="")
+    if res.get("unknown"):
+        print(f"warning: not placeholders: {', '.join('{' + n + '}' for n in res['unknown'])}")
+
+
+def _ticket_scope_to_plan(args: list[str]) -> None:
+    """`agentos ticket scope-to-plan SCOPE [--project KEY] [--modules "A,B"] [--notes TEXT] [-o PLAN.md]`."""
+    from sdk import scope_plan
+
+    if not args or args[0] in ("-h", "--help", "help"):
+        print("usage: agentos ticket scope-to-plan SCOPE.md|SCOPE.txt [--project KEY] [--modules \"A, B\"]")
+        print("         [--notes TEXT] [-o PLAN.md]")
+        print("  The local AI reads a detailed scope document and drafts a ticket plan: a `# Module:` per")
+        print("  module (with its repo when the scope names one), `# Cross-module:` for work spanning")
+        print("  modules, Epics with User Stories (User Story format), Tasks and Bugs. Nothing is created:")
+        print("  review/edit the plan, then `agentos ticket bulk-create PLAN.md --dry-run` and create.")
+        sys.exit(0 if args else 1)
+    pos, opts = _pool_opts(args, ("--project", "--modules", "--notes", "-o", "--output"), ())
+    if len(pos) != 1:
+        print("error: give exactly one scope document (use - to read stdin)")
+        sys.exit(1)
+    try:
+        src = None if pos[0] == "-" else Path(pos[0]).expanduser()
+        scope = sys.stdin.read() if src is None else src.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        print(f"error: cannot read {pos[0]} as text: {exc} (save it as .md or .txt)")
+        sys.exit(1)
+    # Default: next to the scope document, `<name>.plan.md`.
+    out = Path(opts.get("-o") or opts.get("--output") or
+               (src.with_name(src.stem + ".plan.md") if src else Path("scope.plan.md"))).expanduser()
+    if out.exists():
+        print(f"error: {out} already exists — pass -o NEW.md")
+        sys.exit(1)
+    modules = [m.strip() for m in (opts.get("--modules") or "").split(",") if m.strip()]
+    print("drafting the plan with the local AI — a large scope can take several minutes…", flush=True)
+    res = asyncio.run(scope_plan.draft_plan(scope, project=opts.get("--project", ""), modules=modules,
+                                            notes=opts.get("--notes", ""),
+                                            scope_name=src.name if src else "scope.md"))
+    if not res.get("plan"):
+        print(f"error: {res.get('error')}")
+        sys.exit(1)
+    out.write_text(res["plan"], encoding="utf-8")
+    s = res["summary"]
+    print(f"✓ plan written to {out}: {s['modules']} module(s), {s['cross_module']} cross-module section(s), "
+          f"{s['epic']} epic(s), {s['story']} stories, {s['ticket']} standalone ticket(s)")
+    for e in res.get("errors") or []:
+        print(f"  needs fixing: {e}")
+    for w in res.get("warnings") or []:
+        print(f"  warning: {w}")
+    print(f"next: review/edit it, then  agentos ticket bulk-create {_pname(str(out))} --dry-run")
+    sys.exit(0 if res.get("ok") and not res.get("errors") else 1)
+
+
 def _ticket_list(args: list[str]) -> None:
     """`agentos ticket list` / `agentos tickets` — how many in each status, and which."""
     import json as _json
@@ -1309,6 +1821,24 @@ def _ticket_command(args: list[str]) -> None:
     if verb == "list":
         _ticket_list(args[1:])
         return
+    if verb == "instructions":
+        _ticket_bulk_instructions(args[1:])
+        return
+    if verb == "bulk-update":
+        _ticket_bulk_update(args[1:])
+        return
+    if verb in ("bulk-create", "plan"):
+        _ticket_bulk_create(args[1:])
+        return
+    if verb == "scope-to-plan":
+        _ticket_scope_to_plan(args[1:])
+        return
+    if verb == "placeholders":
+        _ticket_placeholders(args[1:])
+        return
+    if verb == "gen-instructions":
+        _ticket_gen_instructions(args[1:])
+        return
     if verb not in {"create", "update", "show", "delete"}:
         _ticket_usage()
         sys.exit(1)