dream-wf 0.1.0

package/templates/hooks/claude-code/dream-wf-guard.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+MUTATING_TOOLS = {"Write", "Edit", "MultiEdit", "Delete"}
+MUTATING_SHELL = re.compile(r"\b(rm|mv|cp|mkdir|touch|npm\s+install|pnpm\s+add|yarn\s+add|bun\s+add|git\s+commit|git\s+push)\b")
+
+
+def find_root(cwd):
+    current = Path(cwd).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".trellis").exists():
+            return candidate
+    return current
+
+
+def active_tasks(root):
+    tasks_dir = root / ".trellis" / "tasks"
+    if not tasks_dir.exists():
+        return []
+
+    result = []
+    for task_json in tasks_dir.glob("*/task.json"):
+        try:
+            data = json.loads(task_json.read_text())
+        except Exception:
+            continue
+        if data.get("status") in {"planning", "in_progress"}:
+            result.append((task_json.parent, data))
+    return result
+
+
+def is_prd_confirmed(task_dir):
+    prd = task_dir / "prd.md"
+    if not prd.exists():
+        return False
+    text = prd.read_text(errors="ignore").lower()
+    markers = ["prd confirmed", "confirmed: true", "status: confirmed", "用户已确认", "已确认"]
+    return any(marker in text for marker in markers)
+
+
+def is_planning_artifact(root, tool_input):
+    if not isinstance(tool_input, dict):
+        return False
+
+    candidate = tool_input.get("path") or tool_input.get("file_path") or tool_input.get("target_file") or ""
+    if not candidate:
+        return False
+
+    try:
+        file_path = Path(candidate)
+        if not file_path.is_absolute():
+            file_path = (root / file_path).resolve()
+        relative = file_path.relative_to(root).as_posix()
+    except Exception:
+        return False
+
+    if not relative.startswith(".trellis/tasks/"):
+        return False
+
+    name = Path(relative).name
+    return (
+        name in {"prd.md", "design.md", "implement.md", "implement.jsonl", "check.jsonl"}
+        or "/research/" in relative
+    )
+
+
+def deny(message):
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": message
+        }
+    }))
+    sys.exit(0)
+
+
+def allow():
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow"
+        }
+    }))
+    sys.exit(0)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        allow()
+
+    tool_name = payload.get("tool_name") or payload.get("tool", "")
+    tool_input = payload.get("tool_input") or payload.get("input") or {}
+    cwd = payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    root = find_root(cwd)
+
+    is_mutating = tool_name in MUTATING_TOOLS
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if tool_name in {"Shell", "Bash"} and MUTATING_SHELL.search(command):
+        is_mutating = True
+
+    if not is_mutating:
+        allow()
+
+    tasks = active_tasks(root)
+    if not tasks:
+        deny("dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or switch dream-wf to advisory mode.")
+
+    planning_tasks = [(task_dir, task) for task_dir, task in tasks if task.get("status") == "planning"]
+    if planning_tasks:
+        if is_planning_artifact(root, tool_input):
+            allow()
+        unconfirmed = [task for task_dir, task in planning_tasks if not is_prd_confirmed(task_dir)]
+        if unconfirmed:
+            deny("dream-wf strict: implementation is blocked while this task is in planning and its PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.")
+
+    allow()
+
+
+if __name__ == "__main__":
+    main()

package/templates/hooks/cursor/dream-wf-guard.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+MUTATING_TOOLS = {"Write", "Edit", "MultiEdit", "Delete"}
+MUTATING_SHELL = re.compile(r"\b(rm|mv|cp|mkdir|touch|npm\s+install|pnpm\s+add|yarn\s+add|bun\s+add|git\s+commit|git\s+push)\b")
+
+
+def find_root(cwd):
+    current = Path(cwd).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".trellis").exists():
+            return candidate
+    return current
+
+
+def active_tasks(root):
+    tasks_dir = root / ".trellis" / "tasks"
+    if not tasks_dir.exists():
+        return []
+
+    result = []
+    for task_json in tasks_dir.glob("*/task.json"):
+        try:
+            data = json.loads(task_json.read_text())
+        except Exception:
+            continue
+        if data.get("status") in {"planning", "in_progress"}:
+            result.append((task_json.parent, data))
+    return result
+
+
+def is_prd_confirmed(task_dir):
+    prd = task_dir / "prd.md"
+    if not prd.exists():
+        return False
+    text = prd.read_text(errors="ignore").lower()
+    markers = ["prd confirmed", "confirmed: true", "status: confirmed", "用户已确认", "已确认"]
+    return any(marker in text for marker in markers)
+
+
+def is_planning_artifact(root, tool_input):
+    if not isinstance(tool_input, dict):
+        return False
+
+    candidate = tool_input.get("path") or tool_input.get("file_path") or tool_input.get("target_file") or ""
+    if not candidate:
+        return False
+
+    try:
+        file_path = Path(candidate)
+        if not file_path.is_absolute():
+            file_path = (root / file_path).resolve()
+        relative = file_path.relative_to(root).as_posix()
+    except Exception:
+        return False
+
+    if not relative.startswith(".trellis/tasks/"):
+        return False
+
+    name = Path(relative).name
+    return (
+        name in {"prd.md", "design.md", "implement.md", "implement.jsonl", "check.jsonl"}
+        or "/research/" in relative
+    )
+
+
+def deny(message):
+    print(json.dumps({
+        "permission": "deny",
+        "user_message": message,
+        "agent_message": message
+    }))
+    sys.exit(0)
+
+
+def allow():
+    print(json.dumps({"permission": "allow"}))
+    sys.exit(0)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        allow()
+
+    tool_name = payload.get("tool_name") or payload.get("tool", "")
+    tool_input = payload.get("tool_input") or payload.get("input") or {}
+    cwd = payload.get("cwd") or os.getcwd()
+    root = find_root(cwd)
+
+    is_mutating = tool_name in MUTATING_TOOLS
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if tool_name in {"Shell", "Bash"} and MUTATING_SHELL.search(command):
+        is_mutating = True
+
+    if not is_mutating:
+        allow()
+
+    tasks = active_tasks(root)
+    if not tasks:
+        deny("dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or explicitly switch dream-wf to advisory mode.")
+
+    planning_tasks = [(task_dir, task) for task_dir, task in tasks if task.get("status") == "planning"]
+    if planning_tasks:
+        if is_planning_artifact(root, tool_input):
+            allow()
+        unconfirmed = [task for task_dir, task in planning_tasks if not is_prd_confirmed(task_dir)]
+        if unconfirmed:
+            deny("dream-wf strict: implementation is blocked while this task is in planning and its PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.")
+
+    allow()
+
+
+if __name__ == "__main__":
+    main()

package/templates/hooks/opencode/dream-wf-guard.js

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const mutatingTools = new Set(['Write', 'Edit', 'MultiEdit', 'Delete']);
+const mutatingShell = /\b(rm|mv|cp|mkdir|touch|npm\s+install|pnpm\s+add|yarn\s+add|bun\s+add|git\s+commit|git\s+push)\b/;
+
+export default function dreamWfGuard() {
+  return {
+    name: 'dream-wf-guard',
+    async 'tool.before'(input) {
+      const toolName = input?.tool || input?.tool_name || '';
+      const toolInput = input?.input || input?.tool_input || {};
+      const cwd = input?.cwd || process.cwd();
+      const root = findRoot(cwd);
+      const command = typeof toolInput.command === 'string' ? toolInput.command : '';
+      const isMutating = mutatingTools.has(toolName) || ((toolName === 'Shell' || toolName === 'Bash') && mutatingShell.test(command));
+
+      if (!isMutating) {
+        return;
+      }
+
+      const tasks = activeTasks(root);
+      if (tasks.length === 0) {
+        throw new Error('dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or switch dream-wf to advisory mode.');
+      }
+
+      const hasPlanningTask = tasks.some(({ task }) => task.status === 'planning');
+      if (hasPlanningTask && isPlanningArtifact(root, toolInput)) {
+        return;
+      }
+
+      const hasUnconfirmedPlanningTask = tasks.some(({ taskDir, task }) => task.status === 'planning' && !isPrdConfirmed(taskDir));
+      if (hasUnconfirmedPlanningTask) {
+        throw new Error('dream-wf strict: implementation is blocked while this task is in planning and its PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.');
+      }
+    }
+  };
+}
+
+function findRoot(cwd) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, '.trellis'))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(cwd);
+    }
+    current = parent;
+  }
+}
+
+function activeTasks(root) {
+  const tasksDir = path.join(root, '.trellis', 'tasks');
+  if (!fs.existsSync(tasksDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(tasksDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const taskDir = path.join(tasksDir, entry.name);
+      const taskJson = path.join(taskDir, 'task.json');
+      if (!fs.existsSync(taskJson)) {
+        return undefined;
+      }
+      try {
+        const task = JSON.parse(fs.readFileSync(taskJson, 'utf8'));
+        return { taskDir, task };
+      } catch {
+        return undefined;
+      }
+    })
+    .filter(Boolean)
+    .filter(({ task }) => task.status === 'planning' || task.status === 'in_progress');
+}
+
+function isPrdConfirmed(taskDir) {
+  const prd = path.join(taskDir, 'prd.md');
+  if (!fs.existsSync(prd)) {
+    return false;
+  }
+  const text = fs.readFileSync(prd, 'utf8').toLowerCase();
+  return ['prd confirmed', 'confirmed: true', 'status: confirmed', '用户已确认', '已确认'].some((marker) => text.includes(marker));
+}
+
+function isPlanningArtifact(root, toolInput) {
+  const candidate = toolInput?.path || toolInput?.file_path || toolInput?.target_file || '';
+  if (!candidate) {
+    return false;
+  }
+
+  let relative;
+  try {
+    const filePath = path.isAbsolute(candidate) ? candidate : path.resolve(root, candidate);
+    relative = path.relative(root, filePath).split(path.sep).join('/');
+  } catch {
+    return false;
+  }
+
+  if (!relative.startsWith('.trellis/tasks/')) {
+    return false;
+  }
+
+  const name = path.basename(relative);
+  return ['prd.md', 'design.md', 'implement.md', 'implement.jsonl', 'check.jsonl'].includes(name) || relative.includes('/research/');
+}

package/templates/rules/claude-code/dream-wf-block.md

@@ -0,0 +1,23 @@
+<!-- DREAM-WF:START -->
+# Dream WF Entry
+
+For every software engineering request in this project, use the Dream WF profile on top of Trellis by default. The user does not need to mention Trellis or dream-wf.
+
+## Default Routing
+
+- First classify the request using Trellis task classification.
+- For conversation-only or tiny inline work, ask whether a Trellis task is needed only if durable tracking would help.
+- For feature work, bug fixes with uncertainty, refactors, architecture decisions, multi-file changes, or unclear requests, create/use a Trellis planning task before implementation.
+
+## PRD First, Grill-Me Style
+
+During planning, do not start by drafting and writing a speculative PRD. Use `dream-wf-grill-prd` behavior first: inspect available context, ask exactly one high-value question at a time, provide 2-3 options and a recommended answer, then update `prd.md` after the user answers.
+
+Do not start implementation until the active Trellis task has a confirmed PRD. Planning artifacts such as `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, and `research/**` are allowed during planning.
+
+## MCP Policy
+
+- Use `fast-context-mcp` for codebase semantic context.
+- Use `grok-search-mcp` for external docs, live web information, and webpage fetch.
+- If a preferred MCP is unavailable, state the fallback reason before using another tool.
+<!-- DREAM-WF:END -->

package/templates/rules/cursor/dream-wf.mdc

@@ -0,0 +1,38 @@
+---
+description: Dream WF Trellis workflow entrypoint
+alwaysApply: true
+---
+
+# Dream WF Entry
+
+For every software engineering request in this project, use the Dream WF profile on top of Trellis by default. The user does not need to mention Trellis or dream-wf.
+
+## Default Routing
+
+- First classify the request using Trellis task classification.
+- For conversation-only or tiny inline work, ask whether a Trellis task is needed only if durable tracking would help.
+- For feature work, bug fixes with uncertainty, refactors, architecture decisions, multi-file changes, or any unclear request, create/use a Trellis planning task before implementation.
+
+## PRD First, Grill-Me Style
+
+During planning, do not start by drafting and writing a speculative PRD.
+
+Instead:
+
+1. Invoke/use the `dream-wf-grill-prd` skill behavior first.
+2. Inspect code, docs, config, existing specs, and task history before asking the user.
+3. Ask exactly one high-value question at a time.
+4. Provide 2-3 options and a recommended answer.
+5. After the user answers, update `prd.md`.
+6. Repeat until blocking open questions are resolved.
+7. Ask for explicit PRD confirmation before implementation.
+
+## Implementation Gate
+
+Do not start implementation until the active Trellis task has a confirmed PRD. Planning artifacts such as `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, and `research/**` are allowed during planning.
+
+## MCP Policy
+
+- Use `fast-context-mcp` for codebase semantic context.
+- Use `grok-search-mcp` for external docs, live web information, and webpage fetch.
+- If a preferred MCP is unavailable, state the fallback reason before using another tool.

package/templates/rules/opencode/dream-wf-block.md

@@ -0,0 +1,23 @@
+<!-- DREAM-WF:START -->
+# Dream WF Entry
+
+For every software engineering request in this project, use the Dream WF profile on top of Trellis by default. The user does not need to mention Trellis or dream-wf.
+
+## Default Routing
+
+- First classify the request using Trellis task classification.
+- For conversation-only or tiny inline work, ask whether a Trellis task is needed only if durable tracking would help.
+- For feature work, bug fixes with uncertainty, refactors, architecture decisions, multi-file changes, or unclear requests, create/use a Trellis planning task before implementation.
+
+## PRD First, Grill-Me Style
+
+During planning, do not start by drafting and writing a speculative PRD. Use `dream-wf-grill-prd` behavior first: inspect available context, ask exactly one high-value question at a time, provide 2-3 options and a recommended answer, then update `prd.md` after the user answers.
+
+Do not start implementation until the active Trellis task has a confirmed PRD. Planning artifacts such as `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, and `research/**` are allowed during planning.
+
+## MCP Policy
+
+- Use `fast-context-mcp` for codebase semantic context.
+- Use `grok-search-mcp` for external docs, live web information, and webpage fetch.
+- If a preferred MCP is unavailable, state the fallback reason before using another tool.
+<!-- DREAM-WF:END -->

package/templates/skills/dream-wf-grill-prd/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: dream-wf-grill-prd
+description: |
+  Use during Trellis planning when creating or refining a PRD. Applies grill-me style clarification: ask one question at a time, inspect code before asking, provide options and a recommended answer, update prd.md after each decision, and require PRD confirmation before implementation.
+---
+
+# Dream WF Grill PRD
+
+You are the Dream WF PRD clarification skill running inside a Trellis planning task.
+
+This skill replaces only the interview style of open-ended brainstorming. It does not replace Trellis task creation, `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, `trellis-before-dev`, `trellis-check`, `trellis-update-spec`, or `trellis-break-loop`.
+
+## Trigger Check
+
+Use this skill when:
+
+- A Trellis task is in `planning`.
+- A PRD is being created or refined.
+- Requirements are ambiguous, multi-step, architectural, or likely to affect specs.
+- The user asks to plan, design, scope, or clarify a task.
+
+If the task is a small inline change and the user declined Trellis task creation, do not force this skill.
+
+## Required Behavior
+
+1. Read the active task directory and existing `prd.md` if present.
+2. Inspect relevant code, configs, docs, existing specs, and task history before asking the user.
+3. Do not start by writing a speculative initial PRD.
+4. Ask exactly one high-value question first.
+5. For each question, provide 2-3 concrete options and your recommended answer.
+6. After the user answers, update `prd.md` immediately.
+7. Track unresolved items under `Open Questions`.
+8. Move confirmed answers into `Requirements`, `Acceptance Criteria`, `Decisions`, `Technical Notes`, or `Out of Scope`.
+9. Add spec candidates when a user answer or design decision should become a project convention.
+10. Continue until no blocking open questions remain.
+11. Show the complete PRD and ask for explicit confirmation before implementation starts.
+
+## PRD Structure
+
+Use or preserve these sections:
+
+```markdown
+# <Task Title>
+
+## Goal
+<What and why in one sentence.>
+
+## In Scope
+- ...
+
+## Out of Scope
+- ...
+
+## Requirements
+- ...
+
+## Acceptance Criteria
+- [ ] ...
+
+## Decisions
+- Context: ...
+- Decision: ...
+- Consequences: ...
+
+## Technical Notes
+- ...
+
+## Spec Candidates
+- Candidate: ...
+  Evidence: ...
+  Needs user confirmation: yes/no
+
+## Open Questions
+- ...
+```
+
+## Question Format
+
+Use this format for each question:
+
+```markdown
+Question: <one decision to resolve>
+
+Options:
+1. <option A>
+2. <option B>
+3. <option C if useful>
+
+Recommended: <your recommendation and why>
+```
+
+## Stop Condition
+
+Do not begin implementation. End by asking for PRD confirmation or by reporting the exact blocker that prevents confirmation.

package/templates/skills/dream-wf-mcp-policy/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: dream-wf-mcp-policy
+description: |
+  Use before codebase exploration, external documentation lookup, live web research, or webpage fetching. Enforces Dream WF MCP priority: fast-context-mcp for semantic code context and grok-search-mcp for external web/docs/fetch tasks.
+---
+
+# Dream WF MCP Policy
+
+Classify the information need before choosing a search or fetch tool.
+
+## Codebase Semantic Context
+
+Use `fast-context-mcp` first when the request needs semantic codebase understanding.
+
+Preferred tool:
+
+- `fast_context_search`
+
+Use for:
+
+- Finding where behavior lives.
+- Tracing architecture or cross-file flows.
+- Discovering relevant files from natural language.
+- Planning implementation or PRD context collection.
+
+Fallback:
+
+- Use exact search only for known symbols, strings, paths, or narrow scoped patterns.
+- If `fast-context-mcp` is unavailable, state the fallback reason before using another tool.
+
+## External Docs and Web Information
+
+Use `grok-search-mcp` first for external documentation, live technical information, webpage fetch, and source discovery.
+
+Preferred tools:
+
+- `web_search`
+- `web_fetch`
+- `web_map`
+- `get_sources`
+
+Fallback:
+
+- Use built-in web tools only if `grok-search-mcp` is unavailable or insufficient.
+- State the fallback reason before using another web tool.
+
+## Strict Mode
+
+In strict mode, do not silently bypass the preferred MCP. If the preferred tool is missing, say so and proceed with the narrowest fallback that can answer the question.
+
+## Security
+
+Never write API keys, tokens, or MCP secrets into tracked project files. Use environment variables, user-level MCP config, or secret managers.

package/templates/spec/guides/dream-wf-mcp-policy.md

@@ -0,0 +1,29 @@
+# Dream WF MCP Policy
+
+This project prefers MCP tools in a fixed order.
+
+## Codebase Semantic Search
+
+Prefer `fast-context-mcp` and `fast_context_search` for semantic codebase understanding:
+
+- Behavior discovery.
+- Architecture tracing.
+- Natural-language code search.
+- Planning context collection.
+
+Use exact search only for known symbols, strings, paths, or narrow patterns.
+
+## External Web and Documentation
+
+Prefer `grok-search-mcp` for external information:
+
+- `web_search` for live search and technical docs.
+- `web_fetch` for webpage content.
+- `web_map` for site structure.
+- `get_sources` for source URLs.
+
+Built-in web tools are fallback only. State the fallback reason before using them.
+
+## Security
+
+Do not commit API keys, tokens, or MCP secrets into project files.

package/templates/spec/guides/dream-wf-prd-policy.md

@@ -0,0 +1,27 @@
+# Dream WF PRD Policy
+
+This project uses `dream-wf` on top of Trellis.
+
+## Policy
+
+- Keep Trellis task lifecycle and artifacts.
+- Use grill-me style clarification during PRD creation and refinement.
+- Do not start planning by writing a speculative initial PRD.
+- Ask one high-value question first.
+- Provide 2-3 options and a recommended answer for each question.
+- Inspect code, docs, config, existing specs, and task history before asking the user.
+- Update `prd.md` only after each confirmed answer, confirmed existing fact, or explicit decision.
+- Treat task creation consent and implementation approval as separate gates.
+- Do not start implementation until the PRD is confirmed.
+
+## Initial Spec Candidates
+
+During bootstrap or planning, spec candidates may come from:
+
+- User answers.
+- PRD decisions.
+- Design decisions.
+- Verified codebase facts.
+- Existing tests, configs, docs, and conventions.
+
+Initial spec candidates require user review before they become stable project conventions.