feat(package): bundle pi-subagents and improve parallel Arc workflow

README.md

@@ -1,6 +1,6 @@
 # Pi Arc Package
 
-Arc issue tracker integration for [Pi](https://pi.dev): packaged Arc skills, prompt templates, session context injection, workflow command aliases, and bundled checklist support via `@juicesharp/rpiv-todo`.
+Arc issue tracker integration for [Pi](https://pi.dev): packaged Arc skills, prompt templates, session context injection, workflow command aliases, bundled checklist support via `@juicesharp/rpiv-todo`, and bundled Arc specialist support via `pi-subagents`.
 
 This package is a Pi-native port of the Claude Code Arc plugin at https://github.com/sentiolabs/arc
 
@@ -29,7 +29,7 @@ This package is a Pi-native port of the Claude Code Arc plugin at https://github
   - `/arc-which` — run `arc which`
   - `/arc-prime` — show cached `arc prime` context
   - `/arc-refresh` — refresh cached `arc prime` context
-  - `/arc-subagents-sync [project|user]` — generate Arc specialist definitions for `pi-subagents`
+  - `/arc-subagents-sync [project|user]` — generate Arc specialist definitions from the bundled `pi-subagents` copy
   - `/arc-plan`, `/arc-build`, `/arc-review`, etc. — friendly aliases for the corresponding skills
 - **Session context injection**:
   - On session start, the extension runs `arc prime` and injects its output into the system prompt as `<arc-context>`.
@@ -49,14 +49,10 @@ This package is a Pi-native port of the Claude Code Arc plugin at https://github
   - Supports `builder`, `code-reviewer`, `doc-writer`, `evaluator`, `issue-manager`, and `spec-reviewer`.
   - Resolves Arc model tiers (`small`, `standard`, `large`) to concrete Pi models so orchestrators can right-size subagent dispatches.
   - Current limitation: `isolation: "worktree"` is recognized but not implemented yet.
-- **Optional `pi-subagents` companion support**:
-  - Run `/arc-subagents-sync` to generate Arc specialist agents (`arc-builder`, `arc-doc-writer`, `arc-spec-reviewer`, `arc-code-reviewer`, `arc-evaluator`, `arc-issue-manager`) in project or user scope.
-  - Arc workflow skills document where the `subagent` tool is a better fit when `pi-subagents` is installed.
-  - Use Arc specialists for Arc gates (especially spec review). Do not substitute generic `worker`/`reviewer` agents, which can drift from Arc prompts and model policy.
-  - Use `subagent({ action: "list" })` and `/agents` after sync to confirm Arc specialist availability.
-  - Use `/subagents-status` to monitor active/recent async Arc specialist runs; idle installed agents are listed by `/agents`, not the status overlay.
-  - Keep `arc_agent` as the self-contained fallback when Arc `pi-subagents` definitions are unavailable.
-  - Claude-style team deployment is intentionally not ported to Pi.
+- **Bundled `pi-subagents` companion support**:
+  - `@sentiolabs/pi-arc` bundles and loads `pi-subagents` by default, so Arc specialists are available without a separate install.
+  - Pi's package docs recommend bundling other Pi packages through `dependencies` + `bundledDependencies`, then referencing their resources through `node_modules/...` paths in the package's `pi` manifest.
+  - If you previously installed standalone `pi-subagents`, remove the standalone package from `~/.pi/agent/settings.json` or project `.pi/settings.json` if duplicate tools or commands appear. The bundled copy from `@sentiolabs/pi-arc` is enough for Arc workflows.
 
 ## Prerequisites
 
@@ -193,7 +189,9 @@ Override the defaults in `~/.pi/agent/settings.json` or project `.pi/settings.js
 
 For compatibility, `arc_agent` still maps legacy aliases: `haiku` → `small`, `sonnet` → `standard`, `opus` → `large`.
 
-## Sync Arc specialists into `pi-subagents`
+## Sync Arc specialists into bundled `pi-subagents`
+
+`@sentiolabs/pi-arc` bundles and loads `pi-subagents` by default, so `/arc-subagents-sync` refreshes the bundled specialist definitions rather than relying on a standalone install.
 
 Use `/arc-subagents-sync` to generate Arc specialist agent files from this package's bundled prompts:
 
@@ -204,8 +202,16 @@ Use `/arc-subagents-sync` to generate Arc specialist agent files from this packa
 - `arc-evaluator`
 - `arc-issue-manager`
 
+Pi's package docs recommend bundling other Pi packages through `dependencies` + `bundledDependencies`, then referencing their resources through `node_modules/...` paths in the package's `pi` manifest.
+
+Bundled resources resolve from `./node_modules/pi-subagents/src/extension/index.ts`, `./node_modules/pi-subagents/skills`, and `./node_modules/pi-subagents/prompts`.
+
 By default, files are written to project scope (`<cwd>/.pi/agents/`). Pass `user` or `--user` to write to `~/.pi/agent/agents/` instead.
 
+If you previously installed standalone `pi-subagents`, remove the standalone package from `~/.pi/agent/settings.json` or project `.pi/settings.json` if duplicate tools or commands appear. The bundled copy from `@sentiolabs/pi-arc` is enough for Arc workflows.
+
+The `issue-manager` agent stays phased: create the epic first, then child tasks next, then dependencies/labels after all IDs exist. This is sequencing only; true parallel issue creation is not enabled yet.
+
 Generated files include a marker comment so reruns can safely update Arc-managed files while preserving manual edits in user-authored files.
 
 After syncing, verify agent registration:
@@ -219,6 +225,15 @@ Use `/subagents-status` to monitor active/recent async Arc specialist runs after
 
 For Arc gates (especially spec compliance), use Arc specialists (`arc-spec-reviewer`, etc.) instead of generic `worker`/`reviewer` agents.
 
+- Keep `arc_agent` as the self-contained fallback when Arc `pi-subagents` definitions are unavailable.
+- Claude-style team deployment is intentionally not ported to Pi.
+
+## Execution lanes
+
+- Sequential Arc build: use when tasks overlap, dependencies are linear, or `pi-subagents` is unavailable.
+- Parallel Arc batch: use when `/arc-plan` provides a T0 foundation, file ownership matrix, parallel batch manifest, and validation matrix.
+- Ant Colony: future/optional lane for large exploratory work; not a replacement for Arc gates in this iteration.
+
 ## Naming differences from the Claude plugin
 
 Claude plugin commands used names like `/arc:create`. Pi prompt templates are filename-based, so this package uses hyphenated names:
@@ -245,7 +260,7 @@ Implemented:
 - Bundled `@juicesharp/rpiv-ask-user-question` package for interactive workflow decisions
 - Pi-native `arc_agent` custom tool for sequential subagent execution
 - `/arc-subagents-sync` command for generating Arc specialist `pi-subagents` definitions
-- Optional guidance for using `pi-subagents` for worktree-isolated evaluator runs and independent parallel builder batches
+- Bundled `pi-subagents` support for worktree-isolated evaluator runs, independent parallel builder batches, and phased issue-manager creation
 - Maintainer-only `/arc-source-sync` workflow for syncing from the Claude Arc plugin source
 
 Not yet implemented:

STACKING.md

@@ -23,7 +23,7 @@ when **all** of the following hold:
 **Don't stack** when:
 
 - Tasks are independent and have no shared files — use arc's
-  [Parallel Dispatch Protocol](./skills/build/SKILL.md#parallel-dispatch-protocol)
+  [Parallel Patch Protocol](./skills/arc-build/SKILL.md#parallel-patch-protocol)
   with worktrees. Stacking dependent tasks and parallelizing independent tasks
   are different problem shapes; don't conflate them.
 - The epic is one task, or a handful of tasks that share files heavily — one PR
@@ -64,7 +64,7 @@ git-spice auth status                # confirm logged into the forge
 
 ### 1. Brainstorm + plan (unchanged)
 
-```
+```text
 /arc:brainstorm                      # produces docs/plans/<file>.md with the marker
 /arc:plan                            # creates epic + tasks with dependencies
 ```
@@ -104,7 +104,7 @@ arc update $TASK --take
 git-spice branch create $SLUG --no-commit
 
 # Dispatch the builder per the normal arc:build flow.
-# Use the model-selection guidance and prompt template from skills/build/SKILL.md.
+# Use the model-selection guidance and prompt template from skills/arc-build/SKILL.md.
 # The builder implements + commits on the new branch.
 #   ↳ run spec-reviewer, code-reviewer, evaluator (if applicable) per the
 #     orchestration loop — they all operate on PRE_TASK_SHA..HEAD on this branch.

agents/issue-manager.md

@@ -94,36 +94,32 @@ The `--parent` flag automatically creates a parent-child dependency. No manual `
 
 ## Processing Task Manifests
 
-When receiving a structured manifest from the `plan` or `brainstorm` skills:
+When receiving a structured manifest from the `plan` or `brainstorm` skills, parse the `## Epic` and `## Tasks` sections to assemble the manifest, then process it in phases:
 
-1. **Parse tasks** from the `## Tasks` section — each `### T<n>: <title>` block defines one task
-2. **Create all tasks in parallel** using concurrent Bash tool calls — arc handles concurrent writes safely. Issue one Bash call per task in a single response:
+1. **Create the epic first** and capture the epic ID.
+2. **Create all child tasks** with the epic as parent before applying dependencies.
    ```bash
    arc create "Task title" --type=task --parent=<epic-id> --stdin <<'EOF'
    Full multi-line description here.
    EOF
    ```
-3. **Track the ID mapping** — record logical name (T1, T2, P1, etc.) → arc ID from each creation output
-4. **Set dependencies** from the `## Dependencies` section, substituting logical names with real IDs:
+3. **Capture the complete task-name-to-ID table**.
+4. **Apply dependencies only after all child IDs exist**.
    ```bash
    arc dep add <real-later-id> <real-earlier-id> --type=blocks
    ```
-5. **Apply labels** from the `## Labels` section — use the API via the arc client:
+5. **Apply labels after dependencies**, or in the same post-creation phase.
    ```bash
    # Labels are managed via the REST API (no CLI command exists)
    # Use arc update to add label context in the description, or
    # note the labels in the summary for the dispatcher to handle
    ```
-6. **Return a markdown summary table** matching the `## Required Output` format:
-   ```
-   | Task | Arc ID   | Title                    |
-   |------|----------|--------------------------|
-   | T1   | PROJ-5.1 | Implement storage layer  |
-   | T2   | PROJ-5.2 | Add API endpoints        |
-   ```
+6. **Return the final ID table and dependency summary**.
+
+**Concurrency note:** Concurrent child-task creation is future work pending Arc CLI/server concurrency verification. Do not claim true parallel CLI issue creation is safe today.
 
 **Handling partial failures**: If a task creation fails mid-manifest:
-- Continue creating the remaining tasks — do not abort the batch
+- Continue creating the remaining tasks in order — do not abort the manifest
 - Report partial results clearly: "Created 4/5 tasks. T3 failed: `<error message>`"
 - Include the ID mapping for all successfully created tasks so the dispatcher can act on what exists
 - Do not attempt to clean up already-created tasks — the dispatcher will decide

package.json

@@ -45,11 +45,13 @@
   },
   "dependencies": {
     "@juicesharp/rpiv-ask-user-question": "^1.0.14",
-    "@juicesharp/rpiv-todo": "^0.12.5"
+    "@juicesharp/rpiv-todo": "^0.12.5",
+    "pi-subagents": "^0.23.0"
   },
   "bundledDependencies": [
     "@juicesharp/rpiv-todo",
-    "@juicesharp/rpiv-ask-user-question"
+    "@juicesharp/rpiv-ask-user-question",
+    "pi-subagents"
   ],
   "peerDependencies": {
     "@mariozechner/pi-ai": "*",
@@ -73,15 +75,18 @@
   },
   "pi": {
     "skills": [
-      "./skills"
+      "./skills",
+      "./node_modules/pi-subagents/skills"
     ],
     "prompts": [
-      "./prompts/*.md"
+      "./prompts/*.md",
+      "./node_modules/pi-subagents/prompts"
     ],
     "extensions": [
       "./extensions/*.ts",
       "./node_modules/@juicesharp/rpiv-todo/index.ts",
-      "./node_modules/@juicesharp/rpiv-ask-user-question/index.ts"
+      "./node_modules/@juicesharp/rpiv-ask-user-question/index.ts",
+      "./node_modules/pi-subagents/src/extension/index.ts"
     ]
   }
 }

skills/arc-brainstorm/SKILL.md

@@ -107,7 +107,24 @@ Create a task for each step below using the bundled `todo` checklist (via `todo`
 
 ### 5. Identify Shared Contracts (Parallel Readiness)
 
-If the design will produce multiple implementation tasks that could run in parallel, explicitly identify the **shared contracts** — types, interfaces, config keys, constants, and function signatures that multiple tasks will reference.
+If the design can produce independent implementation tasks, the brainstorm output must include a `## Parallel Readiness` section **before** `/arc-plan` creates Arc issues. Use these exact subsection headings:
+
+```markdown
+## Parallel Readiness
+
+### T0 Foundation Decision
+
+### File Ownership Matrix
+
+### Parallel Batch Manifest
+
+### Validation Matrix
+```
+
+- `T0 Foundation Decision` records the sequential foundation step that must land first when multiple tasks depend on the same shared contracts.
+- `File Ownership Matrix` assigns every implementation file to exactly one task. Any overlap must be moved to T0, serialized with dependencies, or merged into one task.
+- `Parallel Batch Manifest` lists the batches, their prerequisites, the tasks in each batch, the independence proof, and the validation.
+- `Validation Matrix` shows which checks prove each batch or task is safe to merge.
 
 Contracts fall into two tiers: