dream-wf 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# DREAM-WORKFLOW
+
+Personal Trellis workflow patch installer for Cursor, Claude Code, and OpenCode.
+
+`dream-wf` does not replace Trellis. It installs a small custom profile on top of Trellis:
+
+- PRD clarification uses grill-me behavior automatically; the user does not need to mention `dream-wf`.
+- Trellis task lifecycle, specs, hooks, skills, sub-agents, checks, and finish-work remain native.
+- Initial spec candidates combine user answers, PRD decisions, and verified project facts.
+- Code semantic search prefers `fast-context-mcp`.
+- External docs and live web search prefer `grok-search-mcp`.
+- Strict mode guards against implementation before active task / PRD confirmation.
+
+## Install
+
+```bash
+npx dream-wf init -p cursor
+npx dream-wf init -p claude
+npx dream-wf init -p opencode
+```
+
+`-p` is required. Default install is project-level and default mode is `strict`.
+
+## Commands
+
+```bash
+npx dream-wf init -p cursor
+npx dream-wf doctor -p cursor
+npx dream-wf update -p cursor
+```
+
+Options:
+
+```bash
+-p cursor|claude|opencode
+--mode strict|advisory
+--install-deps
+--developer <name>
+```
+
+## Trellis Dependency
+
+Source: https://github.com/mindfold-ai/trellis
+
+```bash
+npm install -g @mindfoldhq/trellis@latest
+```
+
+Initialize Trellis first, or let `dream-wf` tell you the exact command:
+
+```bash
+trellis init -u your-name --cursor
+trellis init -u your-name --claude
+trellis init -u your-name --opencode
+```
+
+## Grill Me Dependency
+
+Source: https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md
+
+`dream-wf` installs a project-local `dream-wf-grill-prd` skill that vendors the behavior:
+
+- Ask one question at a time.
+- Provide options and a recommended answer.
+- Inspect code before asking when possible.
+- Update `prd.md` after each answer.
+- Require explicit PRD confirmation before implementation.
+
+## Fast Context MCP
+
+Source: https://github.com/SammySnake-d/fast-context-mcp
+
+```bash
+npm install @sammysnake/fast-context-mcp
+```
+
+Example MCP server config:
+
+```json
+{
+  "fast-context": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "--prefer-online",
+      "fast-context-mcp@latest"
+    ],
+    "env": {
+      "WINDSURF_API_KEY": "devin-session-xx"
+    }
+  }
+}
+```
+
+## Grok Search MCP
+
+Source: https://github.com/GuDaStudio/GrokSearch
+
+Requires Python 3.10+ and `uv` / `uvx`.
+
+```json
+{
+  "grok-search": {
+    "type": "stdio",
+    "command": "uvx",
+    "args": [
+      "--from",
+      "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
+      "grok-search"
+    ],
+    "env": {
+      "GROK_API_URL": "https://your-api-endpoint.com/v1",
+      "GROK_API_KEY": "your-grok-api-key",
+      "GROK_MODEL":"your-model",
+      "TAVILY_API_KEY": "optional-tavily-key",
+      "TAVILY_API_URL": "https://api.tavily.com"
+    }
+  }
+}
+```
+
+Do not commit real API keys or MCP secrets into project files.
+
+## Generated Files
+
+Cursor:
+
+- `.cursor/rules/dream-wf.mdc`
+- `.cursor/skills/dream-wf-grill-prd/SKILL.md`
+- `.cursor/skills/dream-wf-mcp-policy/SKILL.md`
+- `.cursor/hooks/dream-wf-guard.py`
+- `.cursor/hooks.json`
+
+Claude Code:
+
+- `CLAUDE.md` dream-wf entry block
+- `.claude/skills/dream-wf-grill-prd/SKILL.md`
+- `.claude/skills/dream-wf-mcp-policy/SKILL.md`
+- `.claude/hooks/dream-wf-guard.py`
+- `.claude/settings.json`
+
+OpenCode:
+
+- `AGENTS.md` dream-wf entry block
+- `.opencode/skills/dream-wf-grill-prd/SKILL.md`
+- `.opencode/skills/dream-wf-mcp-policy/SKILL.md`
+- `.opencode/plugins/dream-wf-guard.js`
+
+Trellis:
+
+- Appends a `Dream WF Profile` section to `.trellis/workflow.md`.
+- Installs `.trellis/spec/guides/dream-wf-prd-policy.md`.
+- Installs `.trellis/spec/guides/dream-wf-mcp-policy.md`.
+
+## Strict Mode
+
+Strict mode blocks mutating actions when:
+
+- No active Trellis task exists.
+- A task is still in `planning` and `prd.md` is not confirmed.
+
+Mark PRD confirmation with one of these markers in `prd.md`:
+
+```markdown
+PRD confirmed
+confirmed: true
+status: confirmed
+```
+
+## Security
+
+Run doctor before committing:
+
+```bash
+npx dream-wf doctor -p cursor
+```
+
+The doctor checks for obvious MCP secret patterns in project files and reports suspicious findings.

package/bin/dream-wf.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli/index.js';
+
+try {
+  await run(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/core/dependencies.md

@@ -0,0 +1,79 @@
+# Dependencies
+
+`dream-wf` expects Trellis plus two MCP servers and the grill-me skill behavior.
+
+## Trellis
+
+Source: https://github.com/mindfold-ai/trellis
+
+```bash
+npm install -g @mindfoldhq/trellis@latest
+```
+
+Initialize per platform:
+
+```bash
+trellis init -u your-name --cursor
+trellis init -u your-name --claude
+trellis init -u your-name --opencode
+```
+
+## Grill Me
+
+Source: https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md
+
+`dream-wf` vendors the behavior as `dream-wf-grill-prd` rather than depending on a global skill installer.
+
+## Fast Context MCP
+
+Source: https://github.com/SammySnake-d/fast-context-mcp
+
+```bash
+npm install @sammysnake/fast-context-mcp
+```
+
+Example MCP server config:
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y",
+    "--prefer-online",
+    "fast-context-mcp@latest"
+  ],
+  "env": {
+    "WINDSURF_API_KEY": "devin-session-xx"
+  }
+}
+```
+
+## Grok Search MCP
+
+Source: https://github.com/GuDaStudio/GrokSearch
+
+Requires Python 3.10+ and `uv`/`uvx`.
+
+Example MCP server config with placeholders only:
+
+```json
+{
+  "grok-search": {
+    "type": "stdio",
+    "command": "uvx",
+    "args": [
+      "--from",
+      "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
+      "grok-search"
+    ],
+    "env": {
+      "GROK_API_URL": "https://your-api-endpoint.com/v1",
+      "GROK_API_KEY": "your-grok-api-key",
+      "TAVILY_API_KEY": "optional-tavily-key",
+      "GROK_MODEL":"your-model-name"
+    }
+  }
+}
+```
+
+Do not commit real MCP API keys into project files.

package/core/grill-prd-policy.md

@@ -0,0 +1,35 @@
+# Grill PRD Policy
+
+Source skill: https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md
+
+Use grill-me behavior during Trellis planning. This replaces only the interview style, not Trellis task creation or planning artifacts.
+
+## Rules
+
+- Ask one question at a time.
+- Resolve decision dependencies one branch at a time.
+- For each question, provide 2-3 concrete options and a recommended answer.
+- If a question can be answered by exploring the codebase, docs, config, existing specs, or task history, explore first instead of asking the user.
+- After each answer, update `prd.md` immediately.
+- Keep open questions explicit until they are answered or intentionally deferred.
+- Do not start implementation until the PRD is reviewed and confirmed.
+
+## Required PRD Sections
+
+- Goal
+- In scope
+- Out of scope
+- Requirements
+- Acceptance criteria
+- Decisions
+- Technical notes
+- Open questions
+- Spec candidates
+
+## Trellis Compatibility
+
+- Keep `task.py create` as the task creation mechanism.
+- Keep `prd.md` as the canonical requirements artifact.
+- Use `design.md` and `implement.md` for complex tasks.
+- Use `implement.jsonl` and `check.jsonl` for stable context files.
+- Continue to use `trellis-before-dev`, `trellis-check`, `trellis-update-spec`, and `trellis-break-loop`.

package/core/mcp-tool-policy.md

@@ -0,0 +1,90 @@
+# MCP Tool Policy
+
+`dream-wf` uses MCP tools deliberately. Classify the information need before searching.
+
+## Preferred Tools
+
+### Codebase Semantic Context
+
+Use `fast-context-mcp` first when the task requires semantic understanding of a codebase.
+
+Source: https://github.com/SammySnake-d/fast-context-mcp
+
+Preferred tool:
+
+- `fast_context_search`
+
+Use it for:
+
+- Finding where a behavior is implemented.
+- Understanding architecture or cross-file flows.
+- Discovering relevant files from a natural-language query.
+- Initial context gathering for PRD, design, or implementation planning.
+
+Fallback:
+
+- Use exact search only when looking for known symbols, strings, paths, or small scoped patterns.
+- If `fast-context-mcp` is unavailable, say why before falling back.
+
+### External Docs and Live Web Information
+
+Use `grok-search-mcp` first for external docs, live technical information, real-time search, webpage fetch, and source discovery.
+
+Source: https://github.com/GuDaStudio/GrokSearch
+
+Preferred tools:
+
+- `web_search`
+- `web_fetch`
+- `web_map`
+- `get_sources`
+
+Use it for:
+
+- Current documentation.
+- API usage and examples.
+- Live technology information.
+- Fetching webpage content.
+- Finding and citing source URLs.
+
+Fallback:
+
+- Use built-in web tools only when `grok-search-mcp` is unavailable or insufficient.
+- State the fallback reason before using another web tool.
+
+## Strict Mode Rules
+
+In strict mode:
+
+- Do not start broad code exploration with plain grep when semantic search is available.
+- Do not use built-in web search before `grok-search-mcp` for external docs or live information.
+- Do not silently degrade when an MCP is unavailable.
+- Do not put API keys or MCP secrets into tracked project files.
+
+## Installation References
+
+Fast Context MCP:
+
+```bash
+npm install @sammysnake/fast-context-mcp
+```
+
+Grok Search MCP requires Python 3.10+ and `uv`/`uvx`. Example MCP command uses placeholders only:
+
+```json
+{
+  "type": "stdio",
+  "command": "uvx",
+  "args": [
+    "--from",
+    "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
+    "grok-search"
+  ],
+  "env": {
+    "GROK_API_URL": "https://your-api-endpoint.com/v1",
+    "GROK_API_KEY": "your-grok-api-key",
+    "TAVILY_API_KEY": "optional-tavily-key",
+    "GROK_MODEL":"your-model-name"
+  }
+}
+```

package/core/spec-bootstrap-policy.md

@@ -0,0 +1,39 @@
+# Spec Bootstrap Policy
+
+Trellis creates `.trellis/spec/` templates during initialization. Those templates are placeholders until the project has a reviewed first spec pass.
+
+## First Spec Pass
+
+Generate candidate specs from three sources:
+
+1. User decisions captured through grill-me PRD clarification.
+2. Product and technical decisions recorded in `prd.md`, `design.md`, and `implement.md`.
+3. Verified project facts from code, tests, configs, docs, and existing conventions.
+
+Do not write speculative architecture as if it is already true.
+
+## New Projects
+
+For new projects, specs should describe decisions that have actually been made:
+
+- Product boundaries and acceptance criteria from the first PRD.
+- Chosen tech stack and package structure.
+- API, component, state, data, error, logging, test, and validation conventions that are needed now.
+- Minimal rules needed for the next task, not a complete imaginary architecture.
+
+## Existing Projects
+
+For existing projects, specs should be evidence-backed:
+
+- Read representative source files before writing conventions.
+- Reference concrete file paths and patterns.
+- Remove rules that cannot be traced to code, docs, or confirmed user decisions.
+- Prefer empty templates over incorrect templates.
+
+## Review Gate
+
+Initial specs are candidates until the user reviews them. After confirmation, future tasks may treat them as project conventions.
+
+## Long-Term Maintenance
+
+Use `trellis-update-spec` after tasks when a reusable learning, decision, gotcha, anti-pattern, or repeated correction should become project memory.

package/core/workflow-profile.md

@@ -0,0 +1,30 @@
+# Dream WF Profile
+
+`dream-wf` is a personal custom patch profile for Trellis. It does not replace Trellis. It installs small, project-level preferences on top of Trellis so Cursor, Claude Code, and OpenCode follow the same workflow.
+
+## Positioning
+
+- Trellis owns task lifecycle, workflow-state injection, specs, task artifacts, context manifests, sub-agent context injection, checks, spec updates, and finish-work.
+- `dream-wf` owns preference patches: grill-me style PRD clarification, MCP tool priority, dependency checks, and strict guardrails.
+- Project files remain the source of truth. Do not rely on chat memory for requirements, project conventions, or task state.
+
+## Preserved Trellis Flow
+
+Keep the native Trellis flow:
+
+1. Classify the user request.
+2. Ask for Trellis task-creation consent when useful.
+3. Create a task and enter `planning`.
+4. Write `prd.md` for every task.
+5. Write `design.md` and `implement.md` for complex tasks.
+6. Curate `implement.jsonl` and `check.jsonl` when stable context manifests are useful.
+7. Start the task and enter `in_progress`.
+8. Run before-dev context loading, implementation, check, update-spec, and finish-work.
+
+## Dream WF Patch Points
+
+- Use `dream-wf-grill-prd` for PRD clarification instead of open-ended brainstorm interviewing.
+- Generate initial spec candidates from user answers, PRD decisions, and verified project facts.
+- Prefer `fast-context-mcp` for codebase semantic search.
+- Prefer `grok-search-mcp` for external docs, live technical information, and webpage fetching.
+- Use strict guardrails to prevent implementation before active task and PRD readiness.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "dream-wf",
+  "version": "0.1.0",
+  "description": "Personal Trellis workflow patch installer for Cursor, Claude Code, and OpenCode.",
+  "type": "module",
+  "bin": {
+    "dream-wf": "bin/dream-wf.js"
+  },
+  "scripts": {
+    "check": "node --check bin/dream-wf.js && node --check src/cli/index.js && node --check src/lib/files.js && node --check src/lib/platforms.js && node --check src/lib/trellis.js && node --check src/lib/json.js && node --check src/doctor/index.js && node --check src/deps/index.js && node --check src/platforms/shared.js && node --check src/platforms/cursor/index.js && node --check src/platforms/claude-code/index.js && node --check src/platforms/opencode/index.js && node --check templates/hooks/opencode/dream-wf-guard.js"
+  },
+  "keywords": [
+    "trellis",
+    "workflow",
+    "cursor",
+    "claude",
+    "opencode",
+    "mcp"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,198 @@
+import process from 'node:process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertSupportedPlatform, normalizePlatform } from '../lib/platforms.js';
+import { ensureTrellisInitialized, installTrellisProfile } from '../lib/trellis.js';
+import { formatRelative } from '../lib/files.js';
+import { installCursor } from '../platforms/cursor/index.js';
+import { installClaudeCode } from '../platforms/claude-code/index.js';
+import { installOpenCode } from '../platforms/opencode/index.js';
+import { runDoctor, formatDoctorReport } from '../doctor/index.js';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export async function run(argv) {
+  const { command, options } = parseArgs(argv);
+
+  if (options.help || command === 'help') {
+    writeOutput(helpText());
+    return;
+  }
+
+  if (!command) {
+    throw new Error(`Missing command.\n\n${helpText()}`);
+  }
+
+  const platform = normalizePlatform(options.platform);
+  assertSupportedPlatform(platform);
+
+  const rootDir = process.cwd();
+  const mode = options.mode ?? 'strict';
+  if (!['strict', 'advisory'].includes(mode)) {
+    throw new Error('Invalid --mode. Use strict or advisory.');
+  }
+
+  if (command === 'init') {
+    await init(rootDir, { ...options, platform, mode });
+    return;
+  }
+
+  if (command === 'doctor') {
+    const report = await runDoctor(rootDir, platform);
+    writeOutput(formatDoctorReport(report));
+    return;
+  }
+
+  if (command === 'update') {
+    await init(rootDir, { ...options, platform, mode });
+    return;
+  }
+
+  if (command === 'uninstall') {
+    throw new Error('uninstall is planned but not implemented in this MVP. Remove dream-wf generated files manually if needed.');
+  }
+
+  throw new Error(`Unknown command "${command}".\n\n${helpText()}`);
+}
+
+async function init(rootDir, options) {
+  writeOutput(formatBanner());
+
+  const results = [];
+  const trellis = await ensureTrellisInitialized(rootDir, options);
+
+  if (!trellis.initialized) {
+    writeOutput([
+      'Trellis is not initialized in this project.',
+      `Run: ${trellis.initCommand}`,
+      'Then rerun dream-wf init.'
+    ].join('\n'));
+    return;
+  }
+
+  results.push(await installTrellisProfile(rootDir));
+
+  if (options.platform === 'cursor') {
+    results.push(...await installCursor(packageRoot, rootDir, options));
+  }
+
+  if (options.platform === 'claude') {
+    results.push(...await installClaudeCode(packageRoot, rootDir, options));
+  }
+
+  if (options.platform === 'opencode') {
+    results.push(...await installOpenCode(packageRoot, rootDir, options));
+  }
+
+  const report = await runDoctor(rootDir, options.platform);
+  writeOutput(`${formatInstallReport(rootDir, results)}\n\n${formatDoctorReport(report)}`);
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = {};
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--install-deps') {
+      options.installDeps = true;
+      continue;
+    }
+
+    if (arg === '--skip-deps') {
+      options.installDeps = false;
+      continue;
+    }
+
+    if (arg === '--yes' || arg === '-y') {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === '-p') {
+      const value = rest[index + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error('Missing value for -p. Use -p <cursor|claude|opencode>.');
+      }
+      options.platform = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--mode') {
+      options.mode = readOptionValue(arg, rest, index);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--mode=')) {
+      options.mode = arg.slice('--mode='.length);
+      continue;
+    }
+
+    if (arg === '--developer') {
+      options.developer = readOptionValue(arg, rest, index);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--developer=')) {
+      options.developer = arg.slice('--developer='.length);
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  return { command, options };
+}
+
+function readOptionValue(arg, rest, index) {
+  const value = rest[index + 1];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${arg}.`);
+  }
+  return value;
+}
+
+function formatInstallReport(rootDir, results) {
+  const lines = ['dream-wf install report:'];
+  for (const result of results.flat().filter(Boolean)) {
+    const suffix = result.reason ? ` (${result.reason})` : '';
+    lines.push(`- ${result.action}: ${formatRelative(rootDir, result.path)}${suffix}`);
+  }
+  return lines.join('\n');
+}
+
+function writeOutput(message) {
+  process.stdout.write(`${message}\n`);
+}
+
+function formatBanner() {
+  const banner = [
+    '██████╗ ██████╗ ███████╗ █████╗ ███╗   ███╗',
+    '██╔══██╗██╔══██╗██╔════╝██╔══██╗████╗ ████║',
+    '██║  ██║██████╔╝█████╗  ███████║██╔████╔██║',
+    '██║  ██║██╔══██╗██╔══╝  ██╔══██║██║╚██╔╝██║',
+    '██████╔╝██║  ██║███████╗██║  ██║██║ ╚═╝ ██║',
+    '╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝',
+    '',
+    '  Dream WF · Trellis workflow profile installer'
+  ].join('\n');
+
+  if (!process.stdout.isTTY || process.env.NO_COLOR) {
+    return banner;
+  }
+
+  return `\u001B[35m${banner}\u001B[0m`;
+}
+
+function helpText() {
+  return `dream-wf\n\nUsage:\n  dream-wf init -p <cursor|claude|opencode> [--mode strict|advisory] [--install-deps --developer <name>]\n  dream-wf doctor -p <cursor|claude|opencode>\n  dream-wf update -p <cursor|claude|opencode>\n\nDefaults:\n  --mode strict\n  project-level install\n\nExamples:\n  npx dream-wf init -p cursor\n  npx dream-wf init -p claude --install-deps --developer ashe\n  npx dream-wf doctor -p opencode`;
+}