@mindfoldhq/trellis 0.6.0-beta.7 → 0.6.0-beta.8

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

@@ -17,13 +17,13 @@ Guide AI through collaborative requirements discovery **before implementation**,
 * **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)
 
 ---
 
 ## When to Use
 
-Triggered from `/` when the user describes a development task, especially when:
+Triggered from {{CMD_REF:start}} when the user describes a development task, especially when:
 
 * requirements are unclear or evolving
 * there are multiple valid implementation paths
@@ -38,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–3 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?"
@@ -63,13 +63,16 @@ 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>)
 ```
 
-Create/seed `prd.md` immediately with what you know:
+Use a slug without a date prefix. `task.py create` adds the `MM-DD-`
+directory prefix automatically.
+
+`task.py create` already created a default `prd.md`. Immediately update it with what you know:
 
 ```markdown
 # brainstorm: <short goal>
@@ -78,7 +81,7 @@ Create/seed `prd.md` immediately with what you know:
 
 <one paragraph: what + why>
 
-## What I already know
+## Background / Known Context
 
 * <facts from user message>
 * <facts discovered from repo/docs>
@@ -91,11 +94,11 @@ Create/seed `prd.md` immediately with what you know:
 
 * <ONLY Blocking / Preference questions; keep list short>
 
-## Requirements (evolving)
+## Requirements
 
 * <start with what is known>
 
-## Acceptance Criteria (evolving)
+## Acceptance Criteria
 
 * [ ] <testable criterion>
 
@@ -110,10 +113,39 @@ Create/seed `prd.md` immediately with what you know:
 
 * <what we will not do in this task>
 
-## Technical Notes
+## Research References
+
+* <links to research/*.md or external references>
+```
+
+For complex tasks, also create/update:
 
-* <files inspected, constraints, links, references>
-* <research notes summary if applicable>
+```markdown
+# design.md
+
+## Technical Design
+
+<boundaries, contracts, data flow, compatibility, tradeoffs>
+
+## Rollout / Rollback
+
+<operational notes if relevant>
+```
+
+```markdown
+# implement.md
+
+## Implementation Checklist
+
+- [ ] <ordered implementation step>
+
+## Validation
+
+- <lint/typecheck/test command>
+
+## Review Gates
+
+- <human or technical checkpoint before start/finish>
 ```
 
 ---
@@ -136,8 +168,8 @@ Before asking questions like "what does the code look like?", gather context you
 
 Write findings into PRD:
 
-* Add to `What I already know`
-* Add constraints/links to `Technical Notes`
+* Add user-visible facts to `Background / Known Context`
+* Write technical findings to `research/*.md`, `design.md`, or `implement.md` as appropriate
 
 ---
 
@@ -146,8 +178,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–2 files, scope well-defined              | Ask 1 confirm question, then implement      |
+| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2–3 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.
@@ -158,7 +190,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:
 
@@ -166,9 +198,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:
 
@@ -176,38 +208,83 @@ 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"
 * The user can't reasonably enumerate options
 
-### Research steps
+### Delegate to `trellis-research` sub-agent (don't research inline)
+
+For each research topic, **spawn a `trellis-research` sub-agent via the Task tool** — don't do WebFetch / WebSearch / `gh api` inline in the main conversation.
+
+Why:
+- The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
+- It persists findings to `{TASK_DIR}/research/<topic>.md` (the contract — see `workflow.md` Phase 1.2)
+- 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.
 
-1. Identify 2�? comparable tools/patterns
+Agent type: `trellis-research`
+Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
+
+❌ Bad (what you must NOT do):
+```
+Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
+          → WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
+          → Write(research/topic.md)
+```
+→ Pollutes main context with raw HTML/JSON, burns tokens.
+
+✅ Good:
+```
+Main agent: Task(subagent_type="trellis-research",
+                 prompt="Research topic A; persist to research/topic-a.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic B; persist to research/topic-b.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic C; persist to research/topic-c.md")
+→ Reads research/topic-{a,b,c}.md after they finish.
+```
+
+### Research steps (to pass into each sub-agent prompt)
+
+Each `trellis-research` sub-agent should:
+
+1. Identify 2–4 comparable tools/patterns for its topic
 2. Summarize common conventions and why they exist
 3. Map conventions onto our repo constraints
-4. Produce **2�? feasible approaches** for our project
+4. Write findings to `{TASK_DIR}/research/<topic>.md`
+
+Main agent then reads the persisted files and produces **2–3 feasible approaches** in PRD.
 
 ### Research output format (PRD)
 
-Add a section in PRD (either within Technical Notes or as its own):
+The PRD itself should only reference the persisted research files, not duplicate their content. Add a `## Research References` section pointing at `research/*.md`.
+
+Optionally, add a convergence section with feasible approaches derived from the research:
 
 ```markdown
+## Research References
+
+* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
+* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
+
 ## Research Notes
 
 ### What similar tools do
@@ -244,15 +321,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–2 bullets each)
 
 1. **Future evolution**
 
-   * What might this feature become in 1�? months?
+   * What might this feature become in 1–3 months?
    * What extension points are worth preserving now?
 
 2. **Related scenarios**
@@ -272,9 +349,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–2 bullets>
+2. Related scenarios: <1–2 bullets>
+3. Failure/edge cases: <1–2 bullets>
 
 For this MVP, which would you like to include (or none)?
 
@@ -286,8 +363,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`
 
 ---
 
@@ -300,7 +377,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`
 
@@ -316,20 +393,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–3 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–3 feasible approaches:
 
 **Approach A: <name>** (Recommended)
 
@@ -358,7 +435,7 @@ Record the outcome in PRD as an ADR-lite section:
 
 ---
 
-## Step 8: Final Confirmation + Implementation Plan
+## Step 8: Final Confirmation + Planning Artifacts
 
 When open questions are resolved, confirm complete requirements with a structured summary:
 
@@ -387,16 +464,13 @@ Here's my understanding of the complete requirements:
 
 * ...
 
-**Technical Approach**:
-<brief summary + key decisions>
-
-**Implementation Plan (small PRs)**:
+**Artifact status**:
 
-* PR1: <scaffolding + tests + minimal plumbing>
-* PR2: <core behavior>
-* PR3: <edge cases + docs + cleanup>
+* prd.md: <ready / needs update>
+* design.md: <not needed for lightweight / ready / missing>
+* implement.md: <not needed for lightweight / ready / missing>
 
-Does this look correct? If yes, I'll proceed with implementation.
+Does this look correct? If yes, the next step is planning review before `task.py start`.
 ```
 
 ### Subtask Decomposition (Complex Tasks)
@@ -433,25 +507,13 @@ python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
 
 * [ ] ...
 
-## Definition of Done
-
-* ...
-
-## Technical Approach
-
-<key design + decisions>
-
-## Decision (ADR-lite)
-
-Context / Decision / Consequences
-
 ## Out of Scope
 
 * ...
 
-## Technical Notes
+## Research References
 
-<constraints, references, files, research notes>
+* <links to research/*.md or external references>
 ```
 
 ---
@@ -468,25 +530,25 @@ Context / Decision / Consequences
 
 ## Integration with Start Workflow
 
-After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
+After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow planning review gate:
 
 ```text
 Brainstorm
-  Step 0: Create task directory + seed PRD
-  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
-  �?
-Task Workflow Phase 3 (Execute)
-  Implement �?Check �?Complete
+  Step 0: Create task directory + update PRD
+  Step 1–7: Discover requirements, research, converge
+  Step 8: Final confirmation → user approves planning artifacts
+  ↓
+Task Workflow Phase 1 (Plan)
+  Lightweight task → PRD-only may be enough
+  Complex task → design.md + implement.md required
+  Sub-agent platforms → curate implement.jsonl / check.jsonl manifests
+  → Review gate → task.py start
+  ↓
+Task Workflow Phase 2 (Execute)
+  Implement → Check → Complete
 ```
 
-The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
+The task directory and PRD already exist from brainstorm, but Phase 1 is not skipped; it owns artifact review and the `task.py start` gate.
 
 ---
 
@@ -494,6 +556,6 @@ The task directory and PRD already exist from brainstorm, so Phase 1 of the Task
 
 | Command | When to Use |
 |---------|-------------|
-| `/` | Entry point that triggers brainstorm |
-| `/` | After implementation is complete |
-| `/` | If new patterns emerge during work |
+| `{{CMD_REF:start}}` | Entry point that triggers brainstorm |
+| `{{CMD_REF:finish-work}}` | After implementation is complete |
+| `{{CMD_REF:update-spec}}` | If new patterns emerge during work |

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

@@ -2,28 +2,96 @@
 description: "Trellis Copilot prompt: check.prompt"
 ---
 
-Check if the code you just wrote follows the development guidelines.
+# Code Quality Check
 
-Execute these steps:
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
 
-1. **Identify changed files**:
-   ```bash
-   git diff --name-only HEAD
-   ```
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Task Artifacts and Applicable Specs
+
+Read the current task artifacts in order:
+
+- `prd.md`
+- `design.md` if present
+- `implement.md` if present
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist
+
+### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
 
-2. **Determine which spec modules apply** based on the changed file paths:
-   ```bash
-   python3 ./.trellis/scripts/get_context.py --mode packages
-   ```
+### Test Coverage
 
-3. **Read the spec index** for each relevant module:
-   ```bash
-   cat .trellis/spec/<package>/<layer>/index.md
-   ```
-   Follow the **"Quality Check"** section in the index.
+- [ ] New function → unit test added?
+- [ ] Bug fix → regression test added?
+- [ ] Changed behavior → existing tests updated?
 
-4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal �?it points you to the actual guideline files. Read those files and review your code against them.
+### Spec Sync
+
+- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
 
-5. **Run lint and typecheck** for the affected package.
+## Step 6: Report and Fix
 
-6. **Report any violations** and fix them if found.
+Report violations found and fix them directly. Re-run project checks after fixes.

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

@@ -122,18 +122,26 @@ python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
 ```
 
-#### Step 4: Create prd.md
+#### Step 4: Update prd.md
 
 ```bash
-cat > "$TASK_DIR/prd.md" << 'EOF'
+# task.py create already created prd.md; edit it with requirements and acceptance criteria.
+$EDITOR "$TASK_DIR/prd.md"
+```
+
+Use this shape:
+
+```markdown
 # Feature: <name>
 
+## Goal
+...
+
 ## Requirements
 - ...
 
 ## Acceptance Criteria
-- ...
-EOF
+- [ ] ...
 ```
 
 #### Step 5: Validate and Start
@@ -181,10 +189,10 @@ python3 ./.trellis/scripts/multi_agent/cleanup.py <branch>          # Cleanup wo
 
 The dispatch agent in worktree will automatically execute:
 
-1. implement �?Implement feature
-2. check �?Check code quality
-3. finish �?Final verification
-4. create-pr �?Create PR
+1. implement �?Implement feature
+2. check �?Check code quality
+3. finish �?Final verification
+4. create-pr �?Create PR
 
 ---