@mindfoldhq/trellis 0.5.7 → 0.5.8

package/dist/migrations/manifests/0.5.8.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.8",
+  "description": "Bug fixes for Codex sub-agent behavior. AI no longer gets stuck waiting on sub-agents that don't exist; `trellis-research` on Codex no longer silently exits without producing files. Pure prompt-layer trim.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- **Removing the sub-agent guidance in `AGENTS.md` stops Codex from calling / waiting on research agents.** Deleted the `## Subagents` section (36 lines, including the \"ALWAYS wait for every spawned subagent\" rule).\n- **Sub-agent mode fix: `trellis-research` on Codex no longer exits prematurely / produces no research files due to missing task context** (the main agent now includes the `Active task:` line when dispatching to research agents too).\n\n**Added:**\n- `CoreRule` block prepended to the `trellis-brainstorm` skill (adapted from https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md ).\n\nNon-Codex platforms (Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid) unchanged.",
+  "migrations": [],
+  "notes": "Pure prompt-layer trim. No Python or TypeScript edits. `trellis update` refreshes AGENTS.md / workflow.md / brainstorm skill content."
+}

package/dist/templates/codex/skills/brainstorm/SKILL.md

@@ -5,6 +5,14 @@ description: "Collaborative requirements discovery session optimized for AI codi
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
+**CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+---
+
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
 
 * **Task-first** (capture ideas immediately)

package/dist/templates/common/skills/brainstorm.md

@@ -1,5 +1,13 @@
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
+**CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+---
+
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
 
 * **Task-first** (capture ideas immediately)
@@ -197,6 +205,8 @@ Why:
 - It returns only `{file path, one-line summary}` to the main agent
 - Independent topics can be **parallelized** — spawn multiple sub-agents in one tool call
 
+> **Codex exception**: on Codex CLI, do NOT dispatch `trellis-research` for research-first mode — do the research inline (WebFetch / WebSearch in the main session) and write findings to `{TASK_DIR}/research/<topic>.md` yourself. Reason: Codex `spawn_agent` runs sub-agents with `fork_turns="none"` (isolated context, no parent session inheritance), so the research sub-agent cannot resolve the active task path via `task.py current` and silently aborts without producing files. Inline research on Codex avoids this failure mode. The 3+ inline research calls limit (B rule in `workflow.md`) is relaxed for Codex specifically.
+
 Agent type: `trellis-research`
 Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
 

package/dist/templates/copilot/prompts/brainstorm.prompt.md

@@ -4,12 +4,20 @@ description: "Trellis Copilot prompt: Brainstorm - Requirements Discovery (AI Co
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
+**CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+---
+
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
 
 * **Task-first** (capture ideas immediately)
 * **Action-before-asking** (reduce low-value questions)
 * **Research-first** for technical choices (avoid asking users to invent options)
-* **Diverge �?Converge** (expand thinking, then lock MVP)
+* **Diverge �?Converge** (expand thinking, then lock MVP)
 
 ---
 
@@ -30,19 +38,19 @@ Triggered from `/` when the user describes a development task, especially when:
    Always ensure a task exists at the start so the user's ideas are recorded immediately.
 
 2. **Action before asking**
-   If you can derive the answer from repo code, docs, configs, conventions, or quick research �?do that first.
+   If you can derive the answer from repo code, docs, configs, conventions, or quick research �?do that first.
 
 3. **One question per message**
    Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
 
 4. **Prefer concrete options**
-   For preference/decision questions, present 2�? feasible, specific approaches with trade-offs.
+   For preference/decision questions, present 2�? feasible, specific approaches with trade-offs.
 
 5. **Research-first for technical choices**
    If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
 
-6. **Diverge �?Converge**
-   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases �?then converge to an MVP with explicit out-of-scope.
+6. **Diverge �?Converge**
+   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases �?then converge to an MVP with explicit out-of-scope.
 
 7. **No meta questions**
    Do not ask "should I search?" or "can you paste the code so I can continue?"
@@ -55,7 +63,7 @@ Triggered from `/` when the user describes a development task, especially when:
 Before any Q&A, ensure a task exists. If none exists, create one immediately.
 
 * Use a **temporary working title** derived from the user's message.
-* It's OK if the title is imperfect �?refine later in PRD.
+* It's OK if the title is imperfect �?refine later in PRD.
 
 ```bash
 TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
@@ -138,8 +146,8 @@ Write findings into PRD:
 | Complexity   | Criteria                                               | Action                                      |
 | ------------ | ------------------------------------------------------ | ------------------------------------------- |
 | **Trivial**  | Single-line fix, typo, obvious change                  | Skip brainstorm, implement directly         |
-| **Simple**   | Clear goal, 1�? files, scope well-defined              | Ask 1 confirm question, then implement      |
-| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2�? high-value questions) |
+| **Simple**   | Clear goal, 1�? files, scope well-defined              | Ask 1 confirm question, then implement      |
+| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2�? high-value questions) |
 | **Complex**  | Vague goal, architectural choices, multiple approaches | Full brainstorm                             |
 
 > Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
@@ -150,7 +158,7 @@ Write findings into PRD:
 
 Before asking ANY question, run the following gate:
 
-### Gate A �?Can I derive this without the user?
+### Gate A �?Can I derive this without the user?
 
 If answer is available via:
 
@@ -158,9 +166,9 @@ If answer is available via:
 * docs/specs/conventions
 * quick market/OSS research
 
-�?**Do not ask.** Fetch it, summarize, update PRD.
+�?**Do not ask.** Fetch it, summarize, update PRD.
 
-### Gate B �?Is this a meta/lazy question?
+### Gate B �?Is this a meta/lazy question?
 
 Examples:
 
@@ -168,21 +176,21 @@ Examples:
 * "Can you paste the code so I can proceed?"
 * "What does the code look like?" (when repo is available)
 
-�?**Do not ask.** Take action.
+�?**Do not ask.** Take action.
 
-### Gate C �?What type of question is it?
+### Gate C �?What type of question is it?
 
 * **Blocking**: cannot proceed without user input
 * **Preference**: multiple valid choices, depends on product/UX/risk preference
 * **Derivable**: should be answered by inspection/research
 
-�?Only ask **Blocking** or **Preference**.
+�?Only ask **Blocking** or **Preference**.
 
 ---
 
 ## Step 4: Research-first Mode (Mandatory for technical choices)
 
-### Trigger conditions (any �?research-first)
+### Trigger conditions (any �?research-first)
 
 * The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
 * The user asks for "best practice", "how others do it", "recommendation"
@@ -190,10 +198,10 @@ Examples:
 
 ### Research steps
 
-1. Identify 2�? comparable tools/patterns
+1. Identify 2�? comparable tools/patterns
 2. Summarize common conventions and why they exist
 3. Map conventions onto our repo constraints
-4. Produce **2�? feasible approaches** for our project
+4. Produce **2�? feasible approaches** for our project
 
 ### Research output format (PRD)
 
@@ -236,15 +244,15 @@ Then ask **one** preference question:
 
 ---
 
-## Step 5: Expansion Sweep (DIVERGE) �?Required after initial understanding
+## Step 5: Expansion Sweep (DIVERGE) �?Required after initial understanding
 
 After you can summarize the goal, proactively broaden thinking before converging.
 
-### Expansion categories (keep to 1�? bullets each)
+### Expansion categories (keep to 1�? bullets each)
 
 1. **Future evolution**
 
-   * What might this feature become in 1�? months?
+   * What might this feature become in 1�? months?
    * What extension points are worth preserving now?
 
 2. **Related scenarios**
@@ -264,9 +272,9 @@ I understand you want to implement: <current goal>.
 
 Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
 
-1. Future evolution: <1�? bullets>
-2. Related scenarios: <1�? bullets>
-3. Failure/edge cases: <1�? bullets>
+1. Future evolution: <1�? bullets>
+2. Related scenarios: <1�? bullets>
+3. Failure/edge cases: <1�? bullets>
 
 For this MVP, which would you like to include (or none)?
 
@@ -278,8 +286,8 @@ For this MVP, which would you like to include (or none)?
 
 Then update PRD:
 
-* What's in MVP �?`Requirements`
-* What's excluded �?`Out of Scope`
+* What's in MVP �?`Requirements`
+* What's excluded �?`Out of Scope`
 
 ---
 
@@ -292,7 +300,7 @@ Then update PRD:
 * After each user answer:
 
   * Update PRD immediately
-  * Move answered items from `Open Questions` �?`Requirements`
+  * Move answered items from `Open Questions` �?`Requirements`
   * Update `Acceptance Criteria` with testable checkboxes
   * Clarify `Out of Scope`
 
@@ -308,20 +316,20 @@ Then update PRD:
 ```markdown
 For <topic>, which approach do you prefer?
 
-1. **Option A** �?<what it means + trade-off>
-2. **Option B** �?<what it means + trade-off>
-3. **Option C** �?<what it means + trade-off>
-4. **Other** �?describe your preference
+1. **Option A** �?<what it means + trade-off>
+2. **Option B** �?<what it means + trade-off>
+3. **Option C** �?<what it means + trade-off>
+4. **Other** �?describe your preference
 ```
 
 ---
 
 ## Step 7: Propose Approaches + Record Decisions (Complex tasks)
 
-After requirements are clear enough, propose 2�? approaches (if not already done via research-first):
+After requirements are clear enough, propose 2�? approaches (if not already done via research-first):
 
 ```markdown
-Based on current information, here are 2�? feasible approaches:
+Based on current information, here are 2�? feasible approaches:
 
 **Approach A: <name>** (Recommended)
 
@@ -465,17 +473,17 @@ After brainstorm completes (Step 8 confirmation approved), the flow continues to
 ```text
 Brainstorm
   Step 0: Create task directory + seed PRD
-  Step 1�?: Discover requirements, research, converge
-  Step 8: Final confirmation �?user approves
-  �?
+  Step 1�?: Discover requirements, research, converge
+  Step 8: Final confirmation �?user approves
+  �?
 Task Workflow Phase 2 (Prepare for Implementation)
   Code-Spec Depth Check (if applicable)
-  �?Research codebase (based on confirmed PRD)
-  �?Configure code-spec context (jsonl files)
-  �?Activate task
-  �?
+  �?Research codebase (based on confirmed PRD)
+  �?Configure code-spec context (jsonl files)
+  �?Activate task
+  �?
 Task Workflow Phase 3 (Execute)
-  Implement �?Check �?Complete
+  Implement �?Check �?Complete
 ```
 
 The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.

package/dist/templates/markdown/agents.md

@@ -16,42 +16,6 @@ If you're using Codex or another agent-capable tool, additional project-scoped h
 - `.agents/skills/` — reusable Trellis skills
 - `.codex/agents/` — optional custom subagents
 
-## Subagents
-
-- ALWAYS wait for every spawned subagent to reach a terminal status before yielding, acting on partial results, or spawning followups.
-  - On Codex, this means calling the `wait` tool with the subagent's thread id (requires `multi_agent_v2`). Do NOT infer completion from elapsed time.
-  - On Claude Code / OpenCode, this means awaiting the Task/agent tool result before continuing.
-- NEVER cancel or re-spawn a subagent that hasn't finished. If a subagent appears stuck, raise the wait timeout (Codex default 30s, max 1h) before judging it broken.
-- Spawn subagents automatically when:
-  - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
-  - Long-running or blocking tasks where a worker can run independently
-  - Isolation for risky changes or checks
-
-### Codex-only — `spawn_agent` parameters
-
-When calling `spawn_agent`, ALWAYS pass `fork_turns="none"`. Without it the child inherits the parent transcript and sees your prior `spawn_agent(...)` records, then applies the "wait for spawned subagents" rule to itself — causing `wait_agent` self-deadlock.
-
-```text
-spawn_agent(agent_type="trellis-implement", message="...", fork_turns="none")
-```
-
-### Codex-only — multi-subagent close-loop
-
-When `wait` returns a `completed` notification, treat it as an event signal — not as "all done". Run this loop:
-
-1. Maintain an `expected_agents` set of dispatched sub-agent thread IDs.
-2. After each `wait` update:
-   1. Call `list_agents` to inspect ALL live agents' status.
-   2. For each agent now in a terminal state:
-      - Verify its promised deliverable exists (e.g. `{task_dir}/research/*.md`).
-      - Read or summarize as needed.
-      - `close_agent` to release the slot.
-      - Remove from `expected_agents`.
-   3. If `expected_agents` still contains running agents → keep waiting.
-   4. If `expected_agents` is empty → continue main flow.
-3. Never `wait` on an agent that has already reported `completed`.
-4. If a `completed` agent is missing its deliverable, treat it as failed — surface that in your report instead of re-waiting.
-
 Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
 
 <!-- TRELLIS:END -->

package/dist/templates/trellis/workflow.md

@@ -151,7 +151,7 @@ Phase 3: Finish  → distill lessons + wrap-up
 
 [workflow-state:no_task]
 No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat; no file writes + one-line answer + repo reads ≤ 2 files → AI judges, no override needed.
-**B Create a task** — any implementation / code change / build / refactor work. Entry sequence: (1) `python3 ./.trellis/scripts/task.py create "<title>"` to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load `trellis-brainstorm` skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run `task.py start <task-dir>` to enter [workflow-state:in_progress] for the implementation skeleton. For research-heavy work, dispatch `trellis-research` sub-agents — main agent must NOT do 3+ inline WebFetch / WebSearch / `gh api` calls. **"It looks small" is NOT grounds for downgrading B to A or C**.
+**B Create a task** — any implementation / code change / build / refactor work. Entry sequence: (1) `python3 ./.trellis/scripts/task.py create "<title>"` to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load `trellis-brainstorm` skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run `task.py start <task-dir>` to enter [workflow-state:in_progress] for the implementation skeleton. **"It looks small" is NOT grounds for downgrading B to A or C**.
 **C Inline change** (per-turn only, escape hatch for B) — the user's CURRENT message MUST contain one of: "skip trellis" / "no task" / "just do it" / "don't create a task" / "跳过 trellis" / "别走流程" / "小修一下" / "直接改" / "先别建任务" → briefly acknowledge ("ok, skipping trellis flow this turn"), then inline. **Without seeing one of these phrases you must NOT inline on your own**; do not invent an override the user never said.
 [/workflow-state:no_task]
 
@@ -169,7 +169,6 @@ No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat;
 Load the `trellis-brainstorm` skill and iterate on prd.md with the user.
 Phase 1.3 (required, once): before `task.py start`, you MUST curate `implement.jsonl` and `check.jsonl` — list the spec / research files sub-agents need so they get the right context injected. You may skip only if the jsonl already has agent-curated entries (the seed `_example` row alone doesn't count).
 Then run `task.py start <task-dir>` to flip status to in_progress.
-Research output **must** land in `{task_dir}/research/*.md`, written by `trellis-research` sub-agents. The main agent should not inline WebFetch / WebSearch — the PRD only links to research files.
 [/workflow-state:planning]
 
 <!-- Per-turn breadcrumb: shown throughout Phase 1 when codex.dispatch_mode=inline.
@@ -182,7 +181,6 @@ Research output **must** land in `{task_dir}/research/*.md`, written by `trellis
 Load the `trellis-brainstorm` skill and iterate on prd.md with the user.
 Phase 1.3 jsonl curation is **skipped** in inline dispatch mode — the main session loads `trellis-before-dev` directly in Phase 2 and reads spec context itself, so there is no sub-agent to inject jsonl into.
 Then run `task.py start <task-dir>` to flip status to in_progress.
-Research output **must** land in `{task_dir}/research/*.md`. In inline mode the main session may do research itself or dispatch `trellis-research` sub-agents.
 [/workflow-state:planning-inline]
 
 ### Phase 2: Execute
@@ -200,7 +198,7 @@ Research output **must** land in `{task_dir}/research/*.md`. In inline mode the
 **Flow**: trellis-implement → trellis-check → trellis-update-spec → commit (Phase 3.4) → `/trellis:finish-work`.
 **Main-session default (no override)**: dispatch the `trellis-implement` / `trellis-check` sub-agents — the main agent does NOT edit code by default. Phase 3.4 commit (required, once): after trellis-update-spec, or whenever implementation is verifiably complete, the main agent **drives the commit** — state the commit plan in user-facing text, then run `git commit` — BEFORE suggesting `/trellis:finish-work`. `/finish-work` refuses to run on a dirty working tree (paths outside `.trellis/workspace/` and `.trellis/tasks/`).
 **Sub-agent self-exemption**: if you are already running as `trellis-implement`, implement directly from the loaded task context and do NOT spawn another `trellis-implement`; if you are already running as `trellis-check`, review/fix directly and do NOT spawn another `trellis-check`. The default dispatch rule applies to the main session only.
-**Sub-agent dispatch protocol (all platforms, all sub-agents EXCEPT trellis-research)**: When you spawn `trellis-implement` / `trellis-check`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) the line is normally redundant — the hook injects context directly — but it serves as a critical fallback when the hook fails (Windows + Claude Code PreToolUse silent skip, `--continue` resume, fork distribution, hooks disabled, etc.). `trellis-research` does not need this line because it operates without a task binding.
+**Sub-agent dispatch protocol (all platforms, all sub-agents)**: When you spawn `trellis-implement` / `trellis-check` / `trellis-research`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) the line is normally redundant — the hook injects context directly — but it serves as a critical fallback when the hook fails (Windows + Claude Code PreToolUse silent skip, `--continue` resume, fork distribution, hooks disabled, etc.). For `trellis-research`, the line tells the sub-agent which `{task_dir}/research/` to write into.
 **Inline override** (per-turn only, escape hatch for sub-agent dispatch): the user's CURRENT message MUST explicitly contain one of: "do it inline" / "no sub-agent" / "你直接改" / "别派 sub-agent" / "main session 写就行" / "不用 sub-agent". **Without seeing one of these phrases you must NOT inline on your own**; do not invent an override the user never said.
 [/workflow-state:in_progress]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",