diff --git a/README.md b/README.md index b82c96a..ebb3547 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

A multi-platform AI coding framework that rules
-Supports Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, Antigravity, Qoder, and CodeBuddy. +Supports Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, Antigravity, Windsurf, Qoder, and CodeBuddy.

@@ -45,7 +45,7 @@ | **Parallel agent execution** | Run multiple AI tasks side by side with git worktrees instead of turning one branch into a traffic jam. | | **Project memory** | Journals in `.trellis/workspace/` preserve what happened last time, so each new session starts with real context. | | **Team-shared standards** | Specs live in the repo, so one person’s hard-won workflow or rule can benefit the whole team. | -| **Multi-platform setup** | Bring the same Trellis structure to 10 AI coding platforms instead of rebuilding your workflow per tool. | +| **Multi-platform setup** | Bring the same Trellis structure to 11 AI coding platforms instead of rebuilding your workflow per tool. | ## Quick Start @@ -61,7 +61,7 @@ trellis init --cursor --opencode --codex -u your-name ``` - `-u your-name` creates `.trellis/workspace/your-name/` for personal journals and session continuity. -- Platform flags can be mixed and matched. Current options include `--cursor`, `--opencode`, `--iflow`, `--codex`, `--kilo`, `--kiro`, `--gemini`, `--antigravity`, `--qoder`, and `--codebuddy`. +- Platform flags can be mixed and matched. Current options include `--cursor`, `--opencode`, `--iflow`, `--codex`, `--kilo`, `--kiro`, `--gemini`, `--antigravity`, `--windsurf`, `--qoder`, and `--codebuddy`. - For platform-specific setup, entry commands, and upgrade paths, use the docs: [Quick Start](https://docs.trytrellis.app/guide/ch02-quick-start) • [Supported Platforms](https://docs.trytrellis.app/guide/ch13-multi-platform) • @@ -138,7 +138,7 @@ Those files are useful, but they tend to become monolithic. Trellis adds structu

Is Trellis only for Claude Code? -No. Trellis currently supports Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, and Antigravity. The detailed setup and entry command for each tool lives in the supported platforms guide. +No. Trellis currently supports Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, Antigravity, and Windsurf. The detailed setup and entry command for each tool lives in the supported platforms guide.
diff --git a/README_CN.md b/README_CN.md index a7f7dd3..713711f 100644 --- a/README_CN.md +++ b/README_CN.md @@ -8,7 +8,7 @@

给 AI 立规矩的开源框架
-支持 Claude Code、Cursor、OpenCode、iFlow、Codex、Kilo、Kiro、Gemini CLI、Antigravity、Qoder 和 CodeBuddy。 +支持 Claude Code、Cursor、OpenCode、iFlow、Codex、Kilo、Kiro、Gemini CLI、Antigravity、Windsurf、Qoder 和 CodeBuddy。

@@ -50,7 +50,7 @@ | **并行 Agent 执行** | 用 git worktree 同时推进多个 AI 任务，不需要把一个分支挤成大杂烩。 | | **项目记忆** | `.trellis/workspace/` 里的 journal 会保留上一次工作的脉络，让新会话不是从空白开始。 | | **团队共享标准** | Spec 跟着仓库一起版本化，一个人总结出来的规则和流程，可以直接变成整个团队的基础设施。 | -| **多平台复用** | 同一套 Trellis 结构可以带到 10 个 AI coding 平台上，而不是每换一个工具就重搭一次工作流。 | +| **多平台复用** | 同一套 Trellis 结构可以带到 11 个 AI coding 平台上，而不是每换一个工具就重搭一次工作流。 | ## 快速开始 @@ -66,7 +66,7 @@ trellis init --cursor --opencode --codex -u your-name ``` - `-u your-name` 会创建 `.trellis/workspace/your-name/`，用来保存个人 journal 和会话连续性。 -- 平台参数可以自由组合。当前可选项包括 `--cursor`、`--opencode`、`--iflow`、`--codex`、`--kilo`、`--kiro`、`--gemini`、`--antigravity`、`--qoder` 和 `--codebuddy`。 +- 平台参数可以自由组合。当前可选项包括 `--cursor`、`--opencode`、`--iflow`、`--codex`、`--kilo`、`--kiro`、`--gemini`、`--antigravity`、`--windsurf`、`--qoder` 和 `--codebuddy`。 - 更完整的安装步骤、各平台入口命令和升级方式放在文档站： [快速开始](https://docs.trytrellis.app/zh/guide/ch02-quick-start) • [支持平台](https://docs.trytrellis.app/zh/guide/ch13-multi-platform) • @@ -143,7 +143,7 @@ trellis init --registry https://github.com/your-org/your-spec-templates

Trellis 只适合 Claude Code 吗？ -不是。Trellis 目前支持 Claude Code、Cursor、OpenCode、iFlow、Codex、Kilo、Kiro、Gemini CLI 和 Antigravity。每个平台的具体接入方式和入口命令，文档站都有单独说明。 +不是。Trellis 目前支持 Claude Code、Cursor、OpenCode、iFlow、Codex、Kilo、Kiro、Gemini CLI、Antigravity 和 Windsurf。每个平台的具体接入方式和入口命令，文档站都有单独说明。
diff --git a/packages/cli/src/cli/index.ts b/packages/cli/src/cli/index.ts index 34baebd..7ddc5d3 100644 --- a/packages/cli/src/cli/index.ts +++ b/packages/cli/src/cli/index.ts @@ -69,6 +69,7 @@ program .option("--kiro", "Include Kiro Code skills") .option("--gemini", "Include Gemini CLI commands") .option("--antigravity", "Include Antigravity workflows") + .option("--windsurf", "Include Windsurf workflows") .option("--qoder", "Include Qoder commands") .option("--codebuddy", "Include CodeBuddy commands") .option("-y, --yes", "Skip prompts and use defaults") diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 2100e35..2833d9c 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -359,6 +359,7 @@ interface InitOptions { kiro?: boolean; gemini?: boolean; antigravity?: boolean; + windsurf?: boolean; qoder?: boolean; codebuddy?: boolean; yes?: boolean; diff --git a/packages/cli/src/configurators/index.ts b/packages/cli/src/configurators/index.ts index 13a0673..88edc07 100644 --- a/packages/cli/src/configurators/index.ts +++ b/packages/cli/src/configurators/index.ts @@ -27,6 +27,7 @@ import { configureKilo } from "./kilo.js"; import { configureKiro } from "./kiro.js"; import { configureGemini } from "./gemini.js"; import { configureAntigravity } from "./antigravity.js"; +import { configureWindsurf } from "./windsurf.js"; import { configureQoder } from "./qoder.js"; import { configureCodebuddy } from "./codebuddy.js"; @@ -59,6 +60,7 @@ import { getAllWorkflows as getKiloWorkflows } from "../templates/kilo/index.js" import { getAllSkills as getKiroSkills } from "../templates/kiro/index.js"; import { getAllCommands as getGeminiCommands } from "../templates/gemini/index.js"; import { getAllWorkflows as getAntigravityWorkflows } from "../templates/antigravity/index.js"; +import { getAllWorkflows as getAllWindsurfWorkflows } from "../templates/windsurf/index.js"; import { getAllSkills as getQoderSkills } from "../templates/qoder/index.js"; import { getAllCommands as getCodebuddyCommands } from "../templates/codebuddy/index.js"; @@ -208,6 +210,16 @@ const PLATFORM_FUNCTIONS: Record = { return files; }, }, + windsurf: { + configure: configureWindsurf, + collectTemplates: () => { + const files = new Map(); + for (const workflow of getAllWindsurfWorkflows()) { + files.set(`.windsurf/workflows/${workflow.name}.md`, workflow.content); + } + return files; + }, + }, qoder: { configure: configureQoder, collectTemplates: () => { diff --git a/packages/cli/src/configurators/windsurf.ts b/packages/cli/src/configurators/windsurf.ts new file mode 100644 index 0000000..7b18c79 --- /dev/null +++ b/packages/cli/src/configurators/windsurf.ts @@ -0,0 +1,19 @@ +import path from "node:path"; +import { getAllWorkflows } from "../templates/windsurf/index.js"; +import { ensureDir, writeFile } from "../utils/file-writer.js"; + +/** + * Configure Windsurf by writing workflow templates. + * + * Output: + * - .windsurf/workflows/.md + */ +export async function configureWindsurf(cwd: string): Promise { + const workflowRoot = path.join(cwd, ".windsurf", "workflows"); + ensureDir(workflowRoot); + + for (const workflow of getAllWorkflows()) { + const targetPath = path.join(workflowRoot, `${workflow.name}.md`); + await writeFile(targetPath, workflow.content); + } +} diff --git a/packages/cli/src/templates/extract.ts b/packages/cli/src/templates/extract.ts index 4e9cf74..b276b6f 100644 --- a/packages/cli/src/templates/extract.ts +++ b/packages/cli/src/templates/extract.ts @@ -212,6 +212,30 @@ export function getAntigravitySourcePath(): string { return getAntigravityTemplatePath(); } +/** + * Get the path to the windsurf templates directory. + * + * This reads from src/templates/windsurf/ (development) or dist/templates/windsurf/ (production). + * These are GENERIC templates, not the Trellis project's own .windsurf/workflows configuration. + */ +export function getWindsurfTemplatePath(): string { + const templatePath = path.join(__dirname, "windsurf"); + if (fs.existsSync(templatePath)) { + return templatePath; + } + + throw new Error( + "Could not find windsurf templates directory. Expected at templates/windsurf/", + ); +} + +/** + * @deprecated Use getWindsurfTemplatePath() instead. + */ +export function getWindsurfSourcePath(): string { + return getWindsurfTemplatePath(); +} + /** * Get the path to the qoder templates directory. * diff --git a/packages/cli/src/templates/trellis/scripts/common/cli_adapter.py b/packages/cli/src/templates/trellis/scripts/common/cli_adapter.py index 483e62e..08910fb 100755 --- a/packages/cli/src/templates/trellis/scripts/common/cli_adapter.py +++ b/packages/cli/src/templates/trellis/scripts/common/cli_adapter.py @@ -1,7 +1,7 @@ """ CLI Adapter for Multi-Platform Support. -Abstracts differences between Claude Code, OpenCode, Cursor, iFlow, Codex, Kilo, Kiro Code, Gemini CLI, Antigravity, Qoder, and CodeBuddy interfaces. +Abstracts differences between Claude Code, OpenCode, Cursor, iFlow, Codex, Kilo, Kiro Code, Gemini CLI, Antigravity, Windsurf, Qoder, and CodeBuddy interfaces. Supported platforms: - claude: Claude Code (default) @@ -13,6 +13,7 @@ - kiro: Kiro Code (skills-based) - gemini: Gemini CLI - antigravity: Antigravity (workflow-based) +- windsurf: Windsurf (workflow-based) - qoder: Qoder - codebuddy: CodeBuddy @@ -43,6 +44,7 @@ "kiro", "gemini", "antigravity", + "windsurf", "qoder", "codebuddy", ] @@ -89,7 +91,7 @@ def config_dir_name(self) -> str: """Get platform-specific config directory name. Returns: - Directory name ('.claude', '.opencode', '.cursor', '.iflow', '.codex', '.kilocode', '.kiro', '.gemini', '.agent', '.qoder', or '.codebuddy') + Directory name ('.claude', '.opencode', '.cursor', '.iflow', '.codex', '.kilocode', '.kiro', '.gemini', '.agent', '.windsurf', '.qoder', or '.codebuddy') """ if self.platform == "opencode": return ".opencode" @@ -107,6 +109,8 @@ def config_dir_name(self) -> str: return ".gemini" elif self.platform == "antigravity": return ".agent" + elif self.platform == "windsurf": + return ".windsurf" elif self.platform == "qoder": return ".qoder" elif self.platform == "codebuddy": @@ -121,7 +125,7 @@ def get_config_dir(self, project_root: Path) -> Path: project_root: Project root directory Returns: - Path to config directory (.claude, .opencode, .cursor, .iflow, .codex, .kilocode, .kiro, .gemini, .agent, .qoder, or .codebuddy) + Path to config directory (.claude, .opencode, .cursor, .iflow, .codex, .kilocode, .kiro, .gemini, .agent, .windsurf, .qoder, or .codebuddy) """ return project_root / self.config_dir_name @@ -153,8 +157,18 @@ def get_commands_path(self, project_root: Path, *parts: str) -> Path: Note: Cursor uses prefix naming: .cursor/commands/trellis-.md Antigravity uses workflow directory: .agent/workflows/.md + Windsurf uses workflow directory: .windsurf/workflows/trellis-.md Claude/OpenCode use subdirectory: .claude/commands/trellis/.md """ + if self.platform == "windsurf": + workflow_dir = self.get_config_dir(project_root) / "workflows" + if not parts: + return workflow_dir + if len(parts) >= 2 and parts[0] == "trellis": + filename = parts[-1] + return workflow_dir / f"trellis-{filename}" + return workflow_dir / Path(*parts) + if self.platform in ("antigravity", "kilo"): workflow_dir = self.get_config_dir(project_root) / "workflows" if not parts: @@ -192,6 +206,7 @@ def get_trellis_command_path(self, name: str) -> str: Kiro: .kiro/skills//SKILL.md Gemini: .gemini/commands/trellis/.toml Antigravity: .agent/workflows/.md + Windsurf: .windsurf/workflows/trellis-.md Others: .{platform}/commands/trellis/.md """ if self.platform == "cursor": @@ -204,6 +219,8 @@ def get_trellis_command_path(self, name: str) -> str: return f".gemini/commands/trellis/{name}.toml" elif self.platform == "antigravity": return f".agent/workflows/{name}.md" + elif self.platform == "windsurf": + return f".windsurf/workflows/trellis-{name}.md" elif self.platform == "kilo": return f".kilocode/workflows/{name}.md" else: @@ -231,6 +248,8 @@ def get_non_interactive_env(self) -> dict[str, str]: return {} # Gemini CLI doesn't have a non-interactive env var elif self.platform == "antigravity": return {} + elif self.platform == "windsurf": + return {} elif self.platform == "qoder": return {} elif self.platform == "codebuddy": @@ -300,6 +319,10 @@ def build_run_command( raise ValueError( "Antigravity workflows are UI slash commands; CLI agent run is not supported." ) + elif self.platform == "windsurf": + raise ValueError( + "Windsurf workflows are UI slash commands; CLI agent run is not supported." + ) elif self.platform == "qoder": cmd = ["qodercli", "-p", prompt] elif self.platform == "codebuddy": @@ -352,6 +375,10 @@ def build_resume_command(self, session_id: str) -> list[str]: raise ValueError( "Antigravity workflows are UI slash commands; CLI resume is not supported." ) + elif self.platform == "windsurf": + raise ValueError( + "Windsurf workflows are UI slash commands; CLI resume is not supported." + ) elif self.platform == "qoder": return ["qodercli", "--resume", session_id] elif self.platform == "codebuddy": @@ -420,6 +447,8 @@ def cli_name(self) -> str: return "gemini" elif self.platform == "antigravity": return "agy" + elif self.platform == "windsurf": + return "windsurf" elif self.platform == "qoder": return "qodercli" elif self.platform == "codebuddy": @@ -488,7 +517,7 @@ def get_cli_adapter(platform: str = "claude") -> CLIAdapter: """Get CLI adapter for the specified platform. Args: - platform: Platform name ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'qoder', or 'codebuddy') + platform: Platform name ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'windsurf', 'qoder', or 'codebuddy') Returns: CLIAdapter instance @@ -506,11 +535,12 @@ def get_cli_adapter(platform: str = "claude") -> CLIAdapter: "kiro", "gemini", "antigravity", + "windsurf", "qoder", "codebuddy", ): raise ValueError( - f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'qoder', or 'codebuddy')" + f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'windsurf', 'qoder', or 'codebuddy')" ) return CLIAdapter(platform=platform) # type: ignore @@ -527,6 +557,7 @@ def get_cli_adapter(platform: str = "claude") -> CLIAdapter: ".kiro", ".gemini", ".agent", + ".windsurf", ".qoder", ".codebuddy", ) @@ -555,15 +586,16 @@ def detect_platform(project_root: Path) -> Platform: 7. .kiro/skills exists and no other platform dirs → kiro 8. .gemini directory exists → gemini 9. .agent/workflows exists and no other platform dirs → antigravity - 10. .codebuddy directory exists → codebuddy - 11. .qoder directory exists → qoder - 12. Default → claude + 10. .windsurf/workflows exists and no other platform dirs → windsurf + 11. .codebuddy directory exists → codebuddy + 12. .qoder directory exists → qoder + 13. Default → claude Args: project_root: Project root directory Returns: - Detected platform ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'qoder', 'codebuddy', or default 'claude') + Detected platform ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'windsurf', 'qoder', 'codebuddy', or default 'claude') """ import os @@ -579,6 +611,7 @@ def detect_platform(project_root: Path) -> Platform: "kiro", "gemini", "antigravity", + "windsurf", "qoder", "codebuddy", ): @@ -626,6 +659,14 @@ def detect_platform(project_root: Path) -> Platform: ): return "antigravity" + # Check for Windsurf workflow directory only when no other platform config exists + if ( + project_root / ".windsurf" / "workflows" + ).is_dir() and not _has_other_platform_dir( + project_root, {".windsurf"} + ): + return "windsurf" + # Check for .codebuddy directory (CodeBuddy-specific) if (project_root / ".codebuddy").is_dir(): return "codebuddy" diff --git a/packages/cli/src/templates/windsurf/index.ts b/packages/cli/src/templates/windsurf/index.ts new file mode 100644 index 0000000..b6e1b28 --- /dev/null +++ b/packages/cli/src/templates/windsurf/index.ts @@ -0,0 +1,55 @@ +/** + * Windsurf workflow templates + * + * These are GENERIC templates for user projects. + * Do NOT use Trellis project's own .windsurf/ directory (which may be customized). + * + * Directory structure: + * windsurf/ + * └── workflows/ # Workflow files + */ + +import { readdirSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +function readTemplate(relativePath: string): string { + return readFileSync(join(__dirname, relativePath), "utf-8"); +} + +function listFiles(dir: string): string[] { + try { + return readdirSync(join(__dirname, dir)); + } catch { + return []; + } +} + +export interface WorkflowTemplate { + name: string; + content: string; +} + +/** + * Get all workflow templates. + * Workflow names match their filename stem + * (e.g. trellis-start.md -> /trellis-start). + */ +export function getAllWorkflows(): WorkflowTemplate[] { + const workflows: WorkflowTemplate[] = []; + + for (const file of listFiles("workflows")) { + if (!file.endsWith(".md")) { + continue; + } + + const name = file.replace(".md", ""); + const content = readTemplate(`workflows/${file}`); + workflows.push({ name, content }); + } + + return workflows; +} diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-before-dev.md b/packages/cli/src/templates/windsurf/workflows/trellis-before-dev.md new file mode 100644 index 0000000..4d95cfa --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-before-dev.md @@ -0,0 +1,31 @@ +--- +description: Read the relevant development guidelines before starting your task. +--- + +Execute these steps: + +1. **Discover packages and their spec layers**: + ```bash + python3 ./.trellis/scripts/get_context.py --mode packages + ``` + +2. **Identify which specs apply** to your task based on: + - Which package you're modifying (e.g., `cli/`, `docs-site/`) + - What type of work (backend, frontend, unit-test, docs, etc.) + +3. **Read the spec index** for each relevant module: + ```bash + cat .trellis/spec///index.md + ``` + Follow the **"Pre-Development Checklist"** section in the index. + +4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns. + +5. **Always read shared guides**: + ```bash + cat .trellis/spec/guides/index.md + ``` + +6. Understand the coding standards and patterns you need to follow, then proceed with your development plan. + +This step is **mandatory** before writing any code. diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-brainstorm.md b/packages/cli/src/templates/windsurf/workflows/trellis-brainstorm.md new file mode 100644 index 0000000..9154e31 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-brainstorm.md @@ -0,0 +1,491 @@ +--- +description: Guide AI through collaborative requirements discovery before implementation, optimized for AI coding workflows. +--- + +# Brainstorm - Requirements Discovery (AI Coding Enhanced) + +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) + +--- + +## When to Use + +Triggered from `/trellis-start` when the user describes a development task, especially when: + +* requirements are unclear or evolving +* there are multiple valid implementation paths +* trade-offs matter (UX, reliability, maintainability, cost, performance) +* the user might not know the best options up front + +--- + +## Core Principles (Non-negotiable) + +1. **Task-first (capture early)** + 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. + +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–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. + +7. **No meta questions** + Do not ask "should I search?" or "can you paste the code so I can continue?" + If you need information: search/inspect. If blocked: ask the minimal blocking question. + +--- + +## Step 0: Ensure Task Exists (ALWAYS) + +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. + +```bash +TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: " --slug ) +``` + +Create/seed `prd.md` immediately with what you know: + +```markdown +# brainstorm: + +## Goal + + + +## What I already know + +* +* + +## Assumptions (temporary) + +* + +## Open Questions + +* + +## Requirements (evolving) + +* + +## Acceptance Criteria (evolving) + +* [ ] + +## Definition of Done (team quality bar) + +* Tests added/updated (unit/integration where appropriate) +* Lint / typecheck / CI green +* Docs/notes updated if behavior changes +* Rollout/rollback considered if risky + +## Out of Scope (explicit) + +* + +## Technical Notes + +* +* +``` + +--- + +## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS) + +Before asking questions like "what does the code look like?", gather context yourself: + +### Repo inspection checklist + +* Identify likely modules/files impacted +* Locate existing patterns (similar features, conventions, error handling style) +* Check configs, scripts, existing command definitions +* Note any constraints (runtime, dependency policy, build tooling) + +### Documentation checklist + +* Look for existing PRDs/specs/templates +* Look for command usage examples, README, ADRs if any + +Write findings into PRD: + +* Add to `What I already know` +* Add constraints/links to `Technical Notes` + +--- + +## Step 2: Classify Complexity (still useful, not gating task creation) + +| Complexity | Criteria | Action | +| ------------ | ------------------------------------------------------ | ------------------------------------------- | +| **Trivial** | Single-line fix, typo, obvious change | Skip brainstorm, implement directly | +| **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. + +--- + +## Step 3: Question Gate (Ask ONLY high-value questions) + +Before asking ANY question, run the following gate: + +### Gate A — Can I derive this without the user? + +If answer is available via: + +* repo inspection (code/config) +* docs/specs/conventions +* quick market/OSS research + +→ **Do not ask.** Fetch it, summarize, update PRD. + +### Gate B — Is this a meta/lazy question? + +Examples: + +* "Should I search?" +* "Can you paste the code so I can proceed?" +* "What does the code look like?" (when repo is available) + +→ **Do not ask.** Take action. + +### 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**. + +--- + +## Step 4: Research-first Mode (Mandatory for technical choices) + +### 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 + +1. Identify 2–4 comparable tools/patterns +2. Summarize common conventions and why they exist +3. Map conventions onto our repo constraints +4. Produce **2–3 feasible approaches** for our project + +### Research output format (PRD) + +Add a section in PRD (either within Technical Notes or as its own): + +```markdown +## Research Notes + +### What similar tools do + +* ... +* ... + +### Constraints from our repo/project + +* ... + +### Feasible approaches here + +**Approach A: ** (Recommended) + +* How it works: +* Pros: +* Cons: + +**Approach B: ** + +* How it works: +* Pros: +* Cons: + +**Approach C: ** (optional) + +* ... +``` + +Then ask **one** preference question: + +* "Which approach do you prefer: A / B / C (or other)?" + +--- + +## 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–2 bullets each) + +1. **Future evolution** + + * What might this feature become in 1–3 months? + * What extension points are worth preserving now? + +2. **Related scenarios** + + * What adjacent commands/flows should remain consistent with this? + * Are there parity expectations (create vs update, import vs export, etc.)? + +3. **Failure & edge cases** + + * Conflicts, offline/network failure, retries, idempotency, compatibility, rollback + * Input validation, security boundaries, permission checks + +### Expansion message template (to user) + +```markdown +I understand you want to implement: . + +Before diving into design, let me quickly diverge to consider three categories (to avoid rework later): + +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)? + +1. Current requirement only (minimal viable) +2. Add (reserve for future extension) +3. Add (improve robustness/consistency) +4. Other: describe your preference +``` + +Then update PRD: + +* What's in MVP → `Requirements` +* What's excluded → `Out of Scope` + +--- + +## Step 6: Q&A Loop (CONVERGE) + +### Rules + +* One question per message +* Prefer multiple-choice when possible +* After each user answer: + + * Update PRD immediately + * Move answered items from `Open Questions` → `Requirements` + * Update `Acceptance Criteria` with testable checkboxes + * Clarify `Out of Scope` + +### Question priority (recommended) + +1. **MVP scope boundary** (what is included/excluded) +2. **Preference decisions** (after presenting concrete options) +3. **Failure/edge behavior** (only for MVP-critical paths) +4. **Success metrics & Acceptance Criteria** (what proves it works) + +### Preferred question format (multiple choice) + +```markdown +For , which approach do you prefer? + +1. **Option A** — +2. **Option B** — +3. **Option C** — +4. **Other** — describe your preference +``` + +--- + +## Step 7: Propose Approaches + Record Decisions (Complex tasks) + +After requirements are clear enough, propose 2–3 approaches (if not already done via research-first): + +```markdown +Based on current information, here are 2–3 feasible approaches: + +**Approach A: ** (Recommended) + +* How: +* Pros: +* Cons: + +**Approach B: ** + +* How: +* Pros: +* Cons: + +Which direction do you prefer? +``` + +Record the outcome in PRD as an ADR-lite section: + +```markdown +## Decision (ADR-lite) + +**Context**: Why this decision was needed +**Decision**: Which approach was chosen +**Consequences**: Trade-offs, risks, potential future improvements +``` + +--- + +## Step 8: Final Confirmation + Implementation Plan + +When open questions are resolved, confirm complete requirements with a structured summary: + +### Final confirmation format + +```markdown +Here's my understanding of the complete requirements: + +**Goal**: + +**Requirements**: + +* ... +* ... + +**Acceptance Criteria**: + +* [ ] ... +* [ ] ... + +**Definition of Done**: + +* ... + +**Out of Scope**: + +* ... + +**Technical Approach**: + + +**Implementation Plan (small PRs)**: + +* PR1: +* PR2: +* PR3: + +Does this look correct? If yes, I'll proceed with implementation. +``` + +### Subtask Decomposition (Complex Tasks) + +For complex tasks with multiple independent work items, create subtasks: + +```bash +# Create child tasks +CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR") +CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR") + +# Or link existing tasks +python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR" +``` + +--- + +## PRD Target Structure (final) + +`prd.md` should converge to: + +```markdown +# + +## Goal + + + +## Requirements + +* ... + +## Acceptance Criteria + +* [ ] ... + +## Definition of Done + +* ... + +## Technical Approach + + + +## Decision (ADR-lite) + +Context / Decision / Consequences + +## Out of Scope + +* ... + +## Technical Notes + + +``` + +--- + +## Anti-Patterns (Hard Avoid) + +* Asking user for code/context that can be derived from repo +* Asking user to choose an approach before presenting concrete options +* Meta questions about whether to research +* Staying narrowly on the initial request without considering evolution/edges +* Letting brainstorming drift without updating PRD + +--- + +## Integration with Start Workflow + +After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**: + +```text +Brainstorm + Step 0: Create task directory + seed PRD + Step 1–7: 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 +``` + +The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely. + +--- + +## Related Commands + +| Command | When to Use | +|---------|-------------| +| `/trellis-start` | Entry point that triggers brainstorm | +| `/trellis-finish-work` | After implementation is complete | +| `/trellis-update-spec` | If new patterns emerge during work | diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-break-loop.md b/packages/cli/src/templates/windsurf/workflows/trellis-break-loop.md new file mode 100644 index 0000000..fa05b91 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-break-loop.md @@ -0,0 +1,111 @@ +--- +description: Analyze completed debugging work to prevent the same class of bugs from recurring. +--- + +# Break the Loop - Deep Bug Analysis + +When debug is complete, use this workflow for deep analysis to break the "fix bug -> forget -> repeat" cycle. + +--- + +## Analysis Framework + +Analyze the bug you just fixed from these 5 dimensions: + +### 1. Root Cause Category + +Which category does this bug belong to? + +| Category | Characteristics | Example | +|----------|-----------------|---------| +| **A. Missing Spec** | No documentation on how to do it | New feature without checklist | +| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected | +| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites | +| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined | +| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds | + +### 2. Why Fixes Failed (if applicable) + +If you tried multiple fixes before succeeding, analyze each failure: + +- **Surface Fix**: Fixed symptom, not root cause +- **Incomplete Scope**: Found root cause, didn't cover all cases +- **Tool Limitation**: grep missed it, type check wasn't strict +- **Mental Model**: Kept looking in same layer, didn't think cross-layer + +### 3. Prevention Mechanisms + +What mechanisms would prevent this from happening again? + +| Type | Description | Example | +|------|-------------|---------| +| **Documentation** | Write it down so people know | Update thinking guide | +| **Architecture** | Make the error impossible structurally | Type-safe wrappers | +| **Compile-time** | TypeScript strict, no any | Signature change causes compile error | +| **Runtime** | Monitoring, alerts, scans | Detect orphan entities | +| **Test Coverage** | E2E tests, integration tests | Verify full flow | +| **Code Review** | Checklist, PR template | "Did you check X?" | + +### 4. Systematic Expansion + +What broader problems does this bug reveal? + +- **Similar Issues**: Where else might this problem exist? +- **Design Flaw**: Is there a fundamental architecture issue? +- **Process Flaw**: Is there a development process improvement? +- **Knowledge Gap**: Is the team missing some understanding? + +### 5. Knowledge Capture + +Solidify insights into the system: + +- [ ] Update `.trellis/spec/guides/` thinking guides +- [ ] Update `.trellis/spec/backend/` or `frontend/` docs +- [ ] Create issue record (if applicable) +- [ ] Create feature ticket for root fix +- [ ] Update check workflows if needed + +--- + +## Output Format + +Please output analysis in this format: + +```markdown +## Bug Analysis: [Short Description] + +### 1. Root Cause Category +- **Category**: [A/B/C/D/E] - [Category Name] +- **Specific Cause**: [Detailed description] + +### 2. Why Fixes Failed (if applicable) +1. [First attempt]: [Why it failed] +2. [Second attempt]: [Why it failed] +... + +### 3. Prevention Mechanisms +| Priority | Mechanism | Specific Action | Status | +|----------|-----------|-----------------|--------| +| P0 | ... | ... | TODO/DONE | + +### 4. Systematic Expansion +- **Similar Issues**: [List places with similar problems] +- **Design Improvement**: [Architecture-level suggestions] +- **Process Improvement**: [Development process suggestions] + +### 5. Knowledge Capture +- [ ] [Documents to update / tickets to create] +``` + +--- + +## Core Philosophy + +> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.** + +Three levels of insight: +1. **Tactical**: How to fix THIS bug +2. **Strategic**: How to prevent THIS CLASS of bugs +3. **Philosophical**: How to expand thinking patterns + +30 minutes of analysis saves 30 hours of future debugging. diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-check-cross-layer.md b/packages/cli/src/templates/windsurf/workflows/trellis-check-cross-layer.md new file mode 100644 index 0000000..c1b7975 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-check-cross-layer.md @@ -0,0 +1,157 @@ +--- +description: Verify that your changes accounted for cross-layer risks and dependencies. +--- + +# Cross-Layer Check + +Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill. + +> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code. + +--- + +## Related Documents + +| Document | Purpose | Timing | +|----------|---------|--------| +| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code | +| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation | +| **`/trellis-check-cross-layer`** (this) | Verification check | **After** implementation | + +--- + +## Execution Steps + +### 1. Identify Change Scope + +```bash +git status +git diff --name-only +``` + +### 2. Select Applicable Check Dimensions + +Based on your change type, execute relevant checks below: + +--- + +## Dimension A: Cross-Layer Data Flow (Required when 3+ layers) + +**Trigger**: Changes involve 3 or more layers + +| Layer | Common Locations | +|-------|------------------| +| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` | +| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` | +| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` | +| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` | +| Utility | `utils/`, `helpers/`, `common/` | + +**Checklist**: +- [ ] Read flow: Database -> Service -> API -> UI +- [ ] Write flow: UI -> API -> Service -> Database +- [ ] Types/schemas correctly passed between layers? +- [ ] Errors properly propagated to caller? +- [ ] Loading/pending states handled at each layer? + +**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md` + +--- + +## Dimension B: Code Reuse (Required when modifying constants/config) + +**Trigger**: +- Modifying UI constants (label, icon, color) +- Modifying any hardcoded value +- Seeing similar code in multiple places +- Creating a new utility/helper function +- Just finished batch modifications across files + +**Checklist**: +- [ ] Search first: How many places define this value? + ```bash + # Search in source files (adjust extensions for your project) + grep -r "value-to-change" src/ + ``` +- [ ] If 2+ places define same value -> Should extract to shared constant +- [ ] After modification, all usage sites updated? +- [ ] If creating utility: Does similar utility already exist? + +**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md` + +--- + +## Dimension B2: New Utility Functions + +**Trigger**: About to create a new utility/helper function + +**Checklist**: +- [ ] Search for existing similar utilities first + ```bash + grep -r "functionNamePattern" src/ + ``` +- [ ] If similar exists, can you extend it instead? +- [ ] If creating new, is it in the right location (shared vs domain-specific)? + +--- + +## Dimension B3: After Batch Modifications + +**Trigger**: Just modified similar patterns in multiple files + +**Checklist**: +- [ ] Did you check ALL files with similar patterns? + ```bash + grep -r "patternYouChanged" src/ + ``` +- [ ] Any files missed that should also be updated? +- [ ] Should this pattern be abstracted to prevent future duplication? + +--- + +## Dimension C: Import/Dependency Paths (Required when creating new files) + +**Trigger**: Creating new source files + +**Checklist**: +- [ ] Using correct import paths (relative vs absolute)? +- [ ] No circular dependencies? +- [ ] Consistent with project's module organization? + +--- + +## Dimension D: Same-Layer Consistency + +**Trigger**: +- Modifying display logic or formatting +- Same domain concept used in multiple places + +**Checklist**: +- [ ] Search for other places using same concept + ```bash + grep -r "ConceptName" src/ + ``` +- [ ] Are these usages consistent? +- [ ] Should they share configuration/constants? + +--- + +## Common Issues Quick Reference + +| Issue | Root Cause | Prevention | +|-------|------------|------------| +| Changed one place, missed others | Didn't search impact scope | `grep` before changing | +| Data lost at some layer | Didn't check data flow | Trace data source to destination | +| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions | +| UI/output inconsistent | Same concept in multiple places | Extract shared constants | +| Similar utility exists | Didn't search first | Search before creating | +| Batch fix incomplete | Didn't verify all occurrences | grep after fixing | + +--- + +## Output + +Report: +1. Which dimensions your changes involve +2. Check results for each dimension +3. Issues found and fix suggestions diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-check.md b/packages/cli/src/templates/windsurf/workflows/trellis-check.md new file mode 100644 index 0000000..051ae35 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-check.md @@ -0,0 +1,27 @@ +--- +description: Check whether the code you just wrote follows the development guidelines. +--- + +Execute these steps: + +1. **Identify changed files**: + ```bash + git diff --name-only HEAD + ``` + +2. **Determine which spec modules apply** based on the changed file paths: + ```bash + python3 ./.trellis/scripts/get_context.py --mode packages + ``` + +3. **Read the spec index** for each relevant module: + ```bash + cat .trellis/spec///index.md + ``` + Follow the **"Quality Check"** section in the index. + +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. + +5. **Run lint and typecheck** for the affected package. + +6. **Report any violations** and fix them if found. diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-create-command.md b/packages/cli/src/templates/windsurf/workflows/trellis-create-command.md new file mode 100644 index 0000000..5e6911d --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-create-command.md @@ -0,0 +1,154 @@ +--- +description: Create a new Windsurf workflow in `.windsurf/workflows/trellis-.md` based on user requirements. +--- + +# Create New Workflow + +## Usage + +``` +/trellis-create-command +``` + +**Example**: +``` +/trellis-create-command review-pr Check PR code changes against project guidelines +``` + +## Execution Steps + +### 1. Parse Input + +Extract from user input: +- **Workflow name**: Use kebab-case (e.g., `review-pr`) +- **Description**: What the workflow should accomplish + +### 2. Analyze Requirements + +Determine workflow type based on description: +- **Initialization**: Read docs, establish context +- **Pre-development**: Read guidelines, check dependencies +- **Code check**: Validate code quality and guideline compliance +- **Recording**: Record progress, questions, structure changes +- **Generation**: Generate docs, code templates + +### 3. Generate Workflow Content + +Based on workflow type, generate appropriate content: + +**Simple workflow** (1-3 lines): +```markdown +Concise instruction describing what to do +``` + +**Complex workflow** (with steps): +```markdown +# Workflow Title + +Workflow description + +## Steps + +### 1. First Step +Specific action + +### 2. Second Step +Specific action + +## Output Format (if needed) + +Template +``` + +### 4. Create Files + +Create: +- `.windsurf/workflows/trellis-.md` + +### 5. Confirm Creation + +Output result: +``` +[OK] Created Workflow: /trellis- + +File paths: +- .windsurf/workflows/trellis-.md + +Usage: +/trellis- + +Description: + +``` + +## Workflow Content Guidelines + +### [OK] Good workflow content + +1. **Clear and concise**: Immediately understandable +2. **Executable**: AI can follow steps directly +3. **Well-scoped**: Clear boundaries of what to do and not do +4. **Has output**: Specifies expected output format (if needed) + +### [X] Avoid + +1. **Too vague**: e.g., "optimize code" +2. **Too complex**: Single workflow should not exceed 100 lines +3. **Duplicate functionality**: Check if similar workflow exists first + +## Naming Conventions + +| Workflow Type | Prefix | Example | +|--------------|--------|---------| +| Session Start | `start` | `start` | +| Pre-development | `before-` | `before-dev` | +| Check | `check-` | `check` | +| Record | `record-` | `record-session` | +| Generate | `generate-` | `generate-api-doc` | +| Update | `update-` | `update-changelog` | +| Other | Verb-first | `review-code`, `sync-data` | + +## Example + +### Input +``` +/trellis-create-command review-pr Check PR code changes against project guidelines +``` + +### Generated Workflow Content +```markdown +# PR Code Review + +Check current PR code changes against project guidelines. + +## Steps + +### 1. Get Changed Files +```bash +git diff main...HEAD --name-only +``` + +### 2. Categorized Review + +**Frontend files** (`apps/web/`): +- Reference `.trellis/spec/frontend/index.md` + +**Backend files** (`packages/api/`): +- Reference `.trellis/spec/backend/index.md` + +### 3. Output Review Report + +Format: + +## PR Review Report + +### Changed Files +- [file list] + +### Check Results +- [OK] Passed items +- [X] Issues found + +### Suggestions +- [improvement suggestions] +``` diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-finish-work.md b/packages/cli/src/templates/windsurf/workflows/trellis-finish-work.md new file mode 100644 index 0000000..fd0bb99 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-finish-work.md @@ -0,0 +1,147 @@ +--- +description: Review work completeness before submitting or committing changes. +--- + +# Finish Work - Pre-Commit Checklist + +Before submitting or committing, use this checklist to ensure work completeness. + +**Timing**: After code is written and tested, before commit + +--- + +## Checklist + +### 1. Code Quality + +```bash +# Must pass +pnpm lint +pnpm type-check +pnpm test +``` + +- [ ] `pnpm lint` passes with 0 errors? +- [ ] `pnpm type-check` passes with no type errors? +- [ ] Tests pass? +- [ ] No `console.log` statements (use logger)? +- [ ] No non-null assertions (the `x!` operator)? +- [ ] No `any` types? + +### 2. Code-Spec Sync + +**Code-Spec Docs**: +- [ ] Does `.trellis/spec/backend/` need updates? + - New patterns, new modules, new conventions +- [ ] Does `.trellis/spec/frontend/` need updates? + - New components, new hooks, new patterns +- [ ] Does `.trellis/spec/guides/` need updates? + - New cross-layer flows, lessons from bugs + +**Key Question**: +> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?" + +If YES -> Update the relevant code-spec doc. + +### 2.5. Code-Spec Hard Block (Infra/Cross-Layer) + +If this change touches infra or cross-layer contracts, this is a blocking checklist: + +- [ ] Spec content is executable (real signatures/contracts), not principle-only text +- [ ] Includes file path + command/API name + payload field names +- [ ] Includes validation and error matrix +- [ ] Includes Good/Base/Bad cases +- [ ] Includes required tests and assertion points + +**Block Rule**: +If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `/trellis-update-spec` manually first. + +### 3. API Changes + +If you modified API endpoints: + +- [ ] Input schema updated? +- [ ] Output schema updated? +- [ ] API documentation updated? +- [ ] Client code updated to match? + +### 4. Database Changes + +If you modified database schema: + +- [ ] Migration file created? +- [ ] Schema file updated? +- [ ] Related queries updated? +- [ ] Seed data updated (if applicable)? + +### 5. Cross-Layer Verification + +If the change spans multiple layers: + +- [ ] Data flows correctly through all layers? +- [ ] Error handling works at each boundary? +- [ ] Types are consistent across layers? +- [ ] Loading states handled? + +### 6. Manual Testing + +- [ ] Feature works in browser/app? +- [ ] Edge cases tested? +- [ ] Error states tested? +- [ ] Works after page refresh? + +--- + +## Quick Check Flow + +```bash +# 1. Code checks +pnpm lint && pnpm type-check + +# 2. View changes +git status +git diff --name-only + +# 3. Based on changed files, check relevant items above +``` + +--- + +## Common Oversights + +| Oversight | Consequence | Check | +|-----------|-------------|-------| +| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ | +| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests | +| Migration not created | Schema out of sync | Check db/migrations/ | +| Types not synced | Runtime errors | Check shared types | +| Tests not updated | False confidence | Run full test suite | +| Console.log left in | Noisy production logs | Search for console.log | + +--- + +## Relationship to Other Commands + +``` +Development Flow: + Write code -> Test -> /trellis-finish-work -> git commit -> /trellis-record-session + | | + Ensure completeness Record progress + +Debug Flow: + Hit bug -> Fix -> /trellis-break-loop -> Knowledge capture + | + Deep analysis +``` + +- `/trellis-finish-work` - Check work completeness (this workflow) +- `/trellis-record-session` - Record session and commits +- `/trellis-break-loop` - Deep analysis after debugging + +--- + +## Core Principle + +> **Delivery includes not just code, but also documentation, verification, and knowledge capture.** + +Complete work = Code + Docs + Tests + Verification diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-integrate-skill.md b/packages/cli/src/templates/windsurf/workflows/trellis-integrate-skill.md new file mode 100644 index 0000000..1b6d9ca --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-integrate-skill.md @@ -0,0 +1,220 @@ +--- +description: Adapt and integrate a reusable skill into your project's development guidelines. +--- + +# Integrate Skill into Project Guidelines + +## Usage + +``` +/trellis-integrate-skill +``` + +**Examples**: +``` +/trellis-integrate-skill frontend-design +/trellis-integrate-skill mcp-builder +``` + +## Core Principle + +> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly. +> +> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md` +> - Code examples -> Place in `.trellis/spec/{target}/examples/skills//` +> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors +> +> Where `{target}` is `frontend` or `backend`, determined by skill type. + +## Execution Steps + +### 1. Read Skill Content + +Locate and read the skill instructions: + +- Skill list in `AGENTS.md` (when available in current context) +- Local repository path to the skill +- Source repository or documentation link shared by the user + +If the skill cannot be found, ask the user for the source path or repository. + +### 2. Determine Integration Target + +Based on skill type, determine which guidelines to update: + +| Skill Category | Integration Target | +|----------------|-------------------| +| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` | +| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` | +| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines | +| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) | + +### 3. Analyze Skill Content + +Extract from the skill: +- **Core concepts**: How the skill works and key concepts +- **Best practices**: Recommended approaches +- **Code patterns**: Reusable code templates +- **Caveats**: Common issues and solutions + +### 4. Execute Integration + +#### 4.1 Update Guidelines Document + +Add a new section to the corresponding `doc.md`: + +```markdown +@@@section:skill- +## # Integration Guide + +### Overview +[Core functionality and use cases of the skill] + +### Project Adaptation +[How to use this skill in the current project] + +### Usage Steps +1. [Step 1] +2. [Step 2] + +### Caveats +- [Project-specific constraints] +- [Differences from default behavior] + +### Reference Examples +See `examples/skills//` + +@@@/section:skill- +``` + +#### 4.2 Create Examples Directory (if code examples exist) + +```bash +# Directory structure ({target} = frontend or backend) +.trellis/spec/{target}/ +|-- doc.md # Add skill-related section +|-- index.md # Update index ++-- examples/ + +-- skills/ + +-- / + |-- README.md # Example documentation + |-- example-1.ts.template # Code example (use .template suffix) + +-- example-2.tsx.template +``` + +**File naming conventions**: +- Code files: `..template` (e.g., `component.tsx.template`) +- Config files: `.config.template` (e.g., `tailwind.config.template`) +- Documentation: `README.md` (normal suffix) + +#### 4.3 Update Index File + +Add to the Quick Navigation table in `index.md`: + +```markdown +| |
| `skill-` | +``` + +### 5. Generate Integration Report + +--- + +## Skill Integration Report: `` + +### # Overview +- **Skill description**: [Functionality description] +- **Integration target**: `.trellis/spec/{target}/` + +### # Tech Stack Compatibility + +| Skill Requirement | Project Status | Compatibility | +|-------------------|----------------|---------------| +| [Tech 1] | [Project tech] | [OK]/[!]/[X] | + +### # Integration Locations + +| Type | Path | +|------|------| +| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-`) | +| Code examples | `.trellis/spec/{target}/examples/skills//` | +| Index update | `.trellis/spec/{target}/index.md` | + +> `{target}` = `frontend` or `backend` + +### # Dependencies (if needed) + +```bash +# Install required dependencies (adjust for your package manager) +npm install +# or +pnpm add +# or +yarn add +``` + +### [OK] Completed Changes + +- [ ] Added `@@@section:skill-` section to `doc.md` +- [ ] Added index entry to `index.md` +- [ ] Created example files in `examples/skills//` +- [ ] Example files use `.template` suffix + +### # Related Guidelines + +- [Existing related section IDs] + +--- + +## 6. Optional: Create Shortcut Workflow + +If this skill is frequently used, create a shortcut workflow: + +```bash +/trellis-create-command use- Use skill following project guidelines +``` + +## Common Skill Integration Reference + +| Skill | Integration Target | Examples Directory | +|-------|-------------------|-------------------| +| `frontend-design` | `frontend` | `examples/skills/frontend-design/` | +| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` | +| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` | +| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) | + +## Example: Integrating `mcp-builder` Skill + +### Directory Structure + +``` +.trellis/spec/backend/ +|-- doc.md # Add MCP section +|-- index.md # Add index entry ++-- examples/ + +-- skills/ + +-- mcp-builder/ + |-- README.md + |-- server.ts.template + |-- tools.ts.template + +-- types.ts.template +``` + +### New Section in doc.md + +```markdown +@@@section:skill-mcp-builder +## # MCP Server Development Guide + +### Overview +Create LLM-callable tool services using MCP (Model Context Protocol). + +### Project Adaptation +- Place services in a dedicated directory +- Follow existing TypeScript and type definition conventions +- Use project's logging system + +### Reference Examples +See `examples/skills/mcp-builder/` + +@@@/section:skill-mcp-builder +``` diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-onboard.md b/packages/cli/src/templates/windsurf/workflows/trellis-onboard.md new file mode 100644 index 0000000..2d6b1a1 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-onboard.md @@ -0,0 +1,362 @@ +--- +description: Onboard a new team member to this project's AI-assisted workflow system. +--- + +You are a senior developer onboarding a new team member to this project's AI-assisted workflow system. + +YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each workflow exists, what problem it solves at a fundamental level. + +## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS + +This onboarding has THREE equally important parts: + +**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, WORKFLOW DEEP DIVE) +- Explain WHY this workflow exists +- Explain WHAT each workflow does and WHY + +**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES) +- Walk through ALL 5 examples in detail +- For EACH step in EACH example, explain: + - PRINCIPLE: Why this step exists + - WHAT HAPPENS: What the workflow actually does + - IF SKIPPED: What goes wrong without it + +**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES) +- Check if project guidelines are still empty templates +- If empty, guide the developer to fill them with project-specific content +- Explain the customization workflow + +DO NOT skip any part. All three parts are essential: +- Part 1 teaches the concepts +- Part 2 shows how concepts work in practice +- Part 3 ensures the project has proper guidelines for AI to follow + +After completing ALL THREE parts, ask the developer about their first task. + +--- + +## CORE PHILOSOPHY: Why This Workflow Exists + +AI-assisted development has three fundamental challenges: + +### Challenge 1: AI Has No Memory + +Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends. + +**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work. + +**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/trellis-start` workflow reads this history at session start, giving AI "artificial memory." + +### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge + +AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions. + +**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules. + +**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `/trellis-before-dev` workflow injects this specialized knowledge into AI context before coding starts. + +### Challenge 3: AI Context Window Is Limited + +Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential. + +**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns. + +**The Solution**: The `/trellis-check-*` workflows re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis-finish-work` workflow does a final holistic review. + +--- + +## SYSTEM STRUCTURE + +``` +.trellis/ +|-- .developer # Your identity (gitignored) +|-- workflow.md # Complete workflow documentation +|-- workspace/ # "AI Memory" - session history +| |-- index.md # All developers' progress +| +-- {developer}/ # Per-developer directory +| |-- index.md # Personal progress index +| +-- journal-N.md # Session records (max 2000 lines) +|-- tasks/ # Task tracking (unified) +| +-- {MM}-{DD}-{slug}/ # Task directory +| |-- task.json # Task metadata +| +-- prd.md # Requirements doc +|-- spec/ # "AI Training Data" - project knowledge +| |-- frontend/ # Frontend conventions +| |-- backend/ # Backend conventions +| +-- guides/ # Thinking patterns ++-- scripts/ # Automation tools +``` + +### Understanding spec/ subdirectories + +**frontend/** - Single-layer frontend knowledge: +- Component patterns (how to write components in THIS project) +- State management rules (Redux? Zustand? Context?) +- Styling conventions (CSS modules? Tailwind? Styled-components?) +- Hook patterns (custom hooks, data fetching) + +**backend/** - Single-layer backend knowledge: +- API design patterns (REST? GraphQL? tRPC?) +- Database conventions (query patterns, migrations) +- Error handling standards +- Logging and monitoring rules + +**guides/** - Cross-layer thinking guides: +- Code reuse thinking guide +- Cross-layer thinking guide +- Pre-implementation checklists + +--- + +## WORKFLOW DEEP DIVE + +### /trellis-start - Restore AI Memory + +**WHY IT EXISTS**: +When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state? + +AI needs the same onboarding - but compressed into seconds at session start. + +**WHAT IT ACTUALLY DOES**: +1. Reads developer identity (who am I in this project?) +2. Checks git status (what branch? uncommitted changes?) +3. Reads recent session history from `workspace/` (what happened before?) +4. Identifies active features (what's in progress?) +5. Understands current project state before making any changes + +**WHY THIS MATTERS**: +- Without /trellis-start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work. +- With /trellis-start: AI knows project context, can continue where previous session left off, avoids conflicts. + +--- + +### /trellis-before-dev - Inject Specialized Knowledge + +**WHY IT EXISTS**: +AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns. + +**WHAT IT ACTUALLY DOES**: +1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines +2. Loads project-specific patterns into AI's working context: + - Component naming conventions + - State management patterns + - Database query patterns + - Error handling standards + +**WHY THIS MATTERS**: +- Without before-dev: AI writes generic code that doesn't match project style. +- With before-dev: AI writes code that looks like the rest of the codebase. + +--- + +### /trellis-check - Combat Context Drift + +**WHY IT EXISTS**: +AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift." + +**WHAT IT ACTUALLY DOES**: +1. Re-reads the guidelines that were injected earlier +2. Compares written code against those guidelines +3. Runs type checker and linter +4. Identifies violations and suggests fixes + +**WHY THIS MATTERS**: +- Without check-*: Context drift goes unnoticed, code quality degrades. +- With check-*: Drift is caught and corrected before commit. + +--- + +### /trellis-check-cross-layer - Multi-Dimension Verification + +**WHY IT EXISTS**: +Most bugs don't come from lack of technical skill - they come from "didn't think of it": +- Changed a constant in one place, missed 5 other places +- Modified database schema, forgot to update the API layer +- Created a utility function, but similar one already exists + +**WHAT IT ACTUALLY DOES**: +1. Identifies which dimensions your change involves +2. For each dimension, runs targeted checks: + - Cross-layer data flow + - Code reuse analysis + - Import path validation + - Consistency checks + +--- + +### /trellis-finish-work - Holistic Pre-Commit Review + +**WHY IT EXISTS**: +The `/trellis-check-*` workflows focus on code quality within a single layer. But real changes often have cross-cutting concerns. + +**WHAT IT ACTUALLY DOES**: +1. Reviews all changes holistically +2. Checks cross-layer consistency +3. Identifies broader impacts +4. Checks if new patterns should be documented + +--- + +### /trellis-record-session - Persist Memory for Future + +**WHY IT EXISTS**: +All the context AI built during this session will be lost when session ends. The next session's `/trellis-start` needs this information. + +**WHAT IT ACTUALLY DOES**: +1. Records session summary to `workspace/{developer}/journal-N.md` +2. Captures what was done, learned, and what's remaining +3. Updates index files for quick lookup + +--- + +## REAL-WORLD WORKFLOW EXAMPLES + +### Example 1: Bug Fix Session + +**[1/8] /trellis-start** - AI needs project context before touching code +**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference +**[3/8] /trellis-before-dev** - Inject project-specific development guidelines +**[4/8] Investigate and fix the bug** - Actual development work +**[5/8] /trellis-check** - Re-verify code against guidelines +**[6/8] /trellis-finish-work** - Holistic cross-layer review +**[7/8] Human tests and commits** - Human validates before code enters repo +**[8/8] /trellis-record-session** - Persist memory for future sessions + +### Example 2: Planning Session (No Code) + +**[1/4] /trellis-start** - Context needed even for non-coding work +**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work +**[3/4] Review docs, create subtask list** - Actual planning work +**[4/4] /trellis-record-session (with --summary)** - Planning decisions must be recorded + +### Example 3: Code Review Fixes + +**[1/6] /trellis-start** - Resume context from previous session +**[2/6] /trellis-before-dev** - Re-inject guidelines before fixes +**[3/6] Fix each CR issue** - Address feedback with guidelines in context +**[4/6] /trellis-check** - Verify fixes did not introduce new issues +**[5/6] /trellis-finish-work** - Document lessons from CR +**[6/6] Human commits, then /trellis-record-session** - Preserve CR lessons + +### Example 4: Large Refactoring + +**[1/5] /trellis-start** - Clear baseline before major changes +**[2/5] Plan phases** - Break into verifiable chunks +**[3/5] Execute phase by phase with /trellis-check after each** - Incremental verification +**[4/5] /trellis-finish-work** - Check if new patterns should be documented +**[5/5] Record with multiple commit hashes** - Link all commits to one feature + +### Example 5: Debug Session + +**[1/6] /trellis-start** - See if this bug was investigated before +**[2/6] /trellis-before-dev** - Guidelines might document known gotchas +**[3/6] Investigation** - Actual debugging work +**[4/6] /trellis-check** - Verify debug changes do not break other things +**[5/6] /trellis-finish-work** - Debug findings might need documentation +**[6/6] Human commits, then /trellis-record-session** - Debug knowledge is valuable + +--- + +## KEY RULES TO EMPHASIZE + +1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates. +2. **Guidelines before code** - /trellis-before-dev workflow injects project knowledge. +3. **Check after code** - /trellis-check-* workflows catch context drift. +4. **Record everything** - /trellis-record-session persists memory. + +--- + +# PART 3: Customize Your Development Guidelines + +After explaining Part 1 and Part 2, check if the project's development guidelines need customization. + +## Step 1: Check Current Guidelines Status + +Check if `.trellis/spec/` contains empty templates or customized guidelines: + +```bash +# Check if files are still empty templates (look for placeholder text) +grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l +grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l +``` + +## Step 2: Determine Situation + +**Situation A: First-time setup (empty templates)** + +If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project. + +Explain to the developer: + +"I see that the development guidelines in `.trellis/spec/` are still empty templates. This is normal for a new Trellis setup! + +The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, the `/trellis-before-dev` workflow won't provide useful guidance. + +**Your first task should be to fill in these guidelines:** + +1. Look at your existing codebase +2. Identify the patterns and conventions already in use +3. Document them in the guideline files + +For example, for `.trellis/spec/backend/database-guidelines.md`: +- What ORM/query library does your project use? +- How are migrations managed? +- What naming conventions for tables/columns? + +Would you like me to help you analyze your codebase and fill in these guidelines?" + +**Situation B: Guidelines already customized** + +If guidelines have real content (no "To be filled" placeholders), this is an existing setup. + +Explain to the developer: + +"Great! Your team has already customized the development guidelines. You can start using the `/trellis-before-dev` workflow right away. + +I recommend reading through `.trellis/spec/` to familiarize yourself with the team's coding standards." + +## Step 3: Help Fill Guidelines (If Empty) + +If the developer wants help filling guidelines, create a feature to track this: + +```bash +python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines +``` + +Then systematically analyze the codebase and fill each guideline file: + +1. **Analyze the codebase** - Look at existing code patterns +2. **Document conventions** - Write what you observe, not ideals +3. **Include examples** - Reference actual files in the project +4. **List forbidden patterns** - Document anti-patterns the team avoids + +Work through one file at a time: +- `backend/directory-structure.md` +- `backend/database-guidelines.md` +- `backend/error-handling.md` +- `backend/quality-guidelines.md` +- `backend/logging-guidelines.md` +- `frontend/directory-structure.md` +- `frontend/component-guidelines.md` +- `frontend/hook-guidelines.md` +- `frontend/state-management.md` +- `frontend/quality-guidelines.md` +- `frontend/type-safety.md` + +--- + +## Completing the Onboard Session + +After covering all three parts, summarize: + +"You're now onboarded to the Trellis workflow system! Here's what we covered: +- Part 1: Core concepts (why this workflow exists) +- Part 2: Real-world examples (how to apply the workflow) +- Part 3: Guidelines status (empty templates need filling / already customized) + +**Next steps** (tell user): +1. Run `/trellis-record-session` to record this onboard session +2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines +3. [If guidelines ready] Start your first development task + +What would you like to do first?" diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-record-session.md b/packages/cli/src/templates/windsurf/workflows/trellis-record-session.md new file mode 100644 index 0000000..bc51a20 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-record-session.md @@ -0,0 +1,66 @@ +--- +description: Record completed work progress after the human has tested and committed the code. +--- + +[!] **Prerequisite**: This workflow should only be used AFTER the human has tested and committed the code. + +**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts. + +--- + +## Record Work Progress + +### Step 1: Get Context & Check Tasks + +```bash +python3 ./.trellis/scripts/get_context.py --mode record +``` + +[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json: +- Code committed? → Archive it (don't wait for PR) +- All acceptance criteria met? → Archive it +- Don't skip archiving just because `status` still says `planning` or `in_progress` + +```bash +python3 ./.trellis/scripts/task.py archive +``` + +### Step 2: One-Click Add Session + +```bash +# Method 1: Simple parameters +python3 ./.trellis/scripts/add_session.py \ + --title "Session Title" \ + --commit "hash1,hash2" \ + --summary "Brief summary of what was done" + +# Method 2: Pass detailed content via stdin +cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash" +| Feature | Description | +|---------|-------------| +| New API | Added user authentication endpoint | +| Frontend | Updated login form | + +**Updated Files**: +- `packages/api/modules/auth/router.ts` +- `apps/web/modules/auth/components/login-form.tsx` +EOF +``` + +**Auto-completes**: +- [OK] Appends session to journal-N.md +- [OK] Auto-detects line count, creates new file if >2000 lines +- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully) +- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history) +- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes + +--- + +## Script Command Reference + +| Command | Purpose | +|---------|---------| +| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session | +| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** | +| `python3 ./.trellis/scripts/task.py archive ` | Archive completed task (auto-commits) | +| `python3 ./.trellis/scripts/task.py list` | List active tasks | diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-start.md b/packages/cli/src/templates/windsurf/workflows/trellis-start.md new file mode 100644 index 0000000..7fd8bd6 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-start.md @@ -0,0 +1,373 @@ +--- +description: Initialize your AI development session and begin working on tasks. +--- + +# Start Session + +--- + +## Operation Types + +Operations in this document are categorized as: + +| Marker | Meaning | Executor | +|--------|---------|----------| +| `[AI]` | Bash scripts or file reads executed by AI | You (AI) | +| `[USER]` | Workflows executed by user | User | + +--- + +## Initialization + +### Step 1: Understand Trellis Workflow `[AI]` + +First, read the workflow guide to understand the development process: + +```bash +cat .trellis/workflow.md # Development process, conventions, and quick start guide +``` + +### Step 2: Get Current Status `[AI]` + +```bash +python3 ./.trellis/scripts/get_context.py +``` + +This returns: +- Developer identity +- Git status (branch, uncommitted changes) +- Recent commits +- Active tasks +- Journal file status + +### Step 3: Read Guidelines Index `[AI]` + +```bash +python3 ./.trellis/scripts/get_context.py --mode packages +``` + +This shows available packages and their spec layers. Read the relevant spec indexes: + +```bash +cat .trellis/spec///index.md # Package-specific guidelines +cat .trellis/spec/guides/index.md # Thinking guides (always read) +``` + +> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). +> At this step, just read the indexes to understand what's available. +> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist. + +### Step 4: Check Active Tasks `[AI]` + +```bash +python3 ./.trellis/scripts/task.py list +``` + +If continuing previous work, review the task file. + +### Step 5: Report Ready Status and Ask for Tasks + +Output a summary: + +```markdown +## Session Initialized + +| Item | Status | +|------|--------| +| Developer | {name} | +| Branch | {branch} | +| Uncommitted | {count} file(s) | +| Journal | {file} ({lines}/2000 lines) | +| Active Tasks | {count} | + +Ready for your task. What would you like to work on? +``` + +--- + +## Task Classification + +When user describes a task, classify it: + +| Type | Criteria | Workflow | +|------|----------|----------| +| **Question** | User asks about code, architecture, or how something works | Answer directly | +| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit | +| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow | +| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** | + +### Decision Rule + +> **If in doubt, use Brainstorm + Task Workflow.** +> +> Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code. +> The overhead is minimal, but the benefit is significant. + +> **Subtask Decomposition**: If brainstorm reveals multiple independent work items, +> consider creating subtasks using `--parent` flag or `add-subtask` command. +> See `/trellis-brainstorm` Step 8 for details. + +--- + +## Question / Trivial Fix + +For questions or trivial fixes, work directly: + +1. Answer question or make the fix +2. If code was changed, remind user to run `/trellis-finish-work` + +--- + +## Simple Task + +For simple, well-defined tasks: + +1. Quick confirm: "I understand you want to [goal]. Shall I proceed?" +2. If no, clarify and confirm again +3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.** + - Create task directory (Phase 1 Path B, Step 2) + - Write PRD (Step 3) + - Research codebase (Phase 2, Step 5) + - Configure context (Step 6) + - Activate task (Step 7) + - Implement (Phase 3, Step 8) + - Check quality (Step 9) + - Complete (Step 10) + +--- + +## Complex Task - Brainstorm First + +For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation. Use `/trellis-brainstorm`. + +Summary: + +1. **Acknowledge and classify** - State your understanding +2. **Create task directory** - Track evolving requirements in `prd.md` +3. **Ask questions one at a time** - Update PRD after each answer +4. **Propose approaches** - For architectural decisions +5. **Confirm final requirements** - Get explicit approval +6. **Proceed to Task Workflow** - With clear requirements in PRD + +--- + +## Task Workflow (Development Tasks) + +**Why this workflow?** +- Run a dedicated research pass before coding +- Configure specs in jsonl context files +- Implement using injected context +- Verify with a separate check pass +- Result: Code that follows project conventions automatically + +### Overview: Two Entry Points + +``` +From Brainstorm (Complex Task): + PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete + +From Simple Task: + Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete +``` + +**Key principle: Research happens AFTER requirements are clear (PRD exists).** + +--- + +### Phase 1: Establish Requirements + +#### Path A: From Brainstorm (skip to Phase 2) + +PRD and task directory already exist from brainstorm. Skip directly to Phase 2. + +#### Path B: From Simple Task + +**Step 1: Confirm Understanding** `[AI]` + +Quick confirm: +- What is the goal? +- What type of development? (frontend / backend / fullstack) +- Any specific requirements or constraints? + +If unclear, ask clarifying questions. + +**Step 2: Create Task Directory** `[AI]` + +```bash +TASK_DIR=$(python3 ./.trellis/scripts/task.py create "" --slug <name>) +``` + +**Step 3: Write PRD** `[AI]` + +Create `prd.md` in the task directory with: + +```markdown +# <Task Title> + +## Goal +<What we're trying to achieve> + +## Requirements +- <Requirement 1> +- <Requirement 2> + +## Acceptance Criteria +- [ ] <Criterion 1> +- [ ] <Criterion 2> + +## Technical Notes +<Any technical decisions or constraints> +``` + +--- + +### Phase 2: Prepare for Implementation (shared) + +> Both paths converge here. PRD and task directory must exist before proceeding. + +**Step 4: Code-Spec Depth Check** `[AI]` + +If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined. + +Trigger this requirement when the change includes any of: +- New or changed command/API signatures +- Database schema or migration changes +- Infra integrations (storage, queue, cache, secrets, env contracts) +- Cross-layer payload transformations + +Must-have before proceeding: +- [ ] Target code-spec files to update are identified +- [ ] Concrete contract is defined (signature, fields, env keys) +- [ ] Validation and error matrix is defined +- [ ] At least one Good/Base/Bad case is defined + +**Step 5: Research the Codebase** `[AI]` + +Based on the confirmed PRD, run a focused research pass and produce: + +1. Relevant spec files in `.trellis/spec/` +2. Existing code patterns to follow (2-3 examples) +3. Files that will likely need modification + +Use this output format: + +```markdown +## Relevant Specs +- <path>: <why it's relevant> + +## Code Patterns Found +- <pattern>: <example file path> + +## Files to Modify +- <path>: <what change> +``` + +**Step 6: Configure Context** `[AI]` + +Initialize default context: + +```bash +python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> +# type: backend | frontend | fullstack +``` + +Add specs found in your research pass: + +```bash +# For each relevant spec and code pattern: +python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>" +python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>" +``` + +**Step 7: Activate Task** `[AI]` + +```bash +python3 ./.trellis/scripts/task.py start "$TASK_DIR" +``` + +This sets `.current-task` so hooks can inject context. + +--- + +### Phase 3: Execute (shared) + +**Step 8: Implement** `[AI]` + +Implement the task described in `prd.md`. + +- Follow all specs injected into implement context +- Keep changes scoped to requirements +- Run lint and typecheck before finishing + +**Step 9: Check Quality** `[AI]` + +Run a quality pass against check context: + +- Review all code changes against the specs +- Fix issues directly +- Ensure lint and typecheck pass + +**Step 10: Complete** `[AI]` + +1. Verify lint and typecheck pass +2. Report what was implemented +3. Remind user to: + - Test the changes + - Commit when ready + - Run `/trellis-record-session` to record this session + +--- + +## User Available Workflows `[USER]` + +The following workflows are for users (not AI): + +| Workflow | Description | +|---------|-------------| +| `/trellis-start` | Start development session (this workflow) | +| `/trellis-brainstorm` | Clarify vague requirements before implementation | +| `/trellis-before-dev` | Read development guidelines | +| `/trellis-check` | Check code quality | +| `/trellis-check-cross-layer` | Cross-layer verification | +| `/trellis-finish-work` | Pre-commit checklist | +| `/trellis-record-session` | Record session progress | + +--- + +## AI Executed Scripts `[AI]` + +| Script | Purpose | +|--------|---------| +| `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create task directory | +| `python3 ./.trellis/scripts/task.py list` | List active tasks | +| `python3 ./.trellis/scripts/task.py archive <name>` | Archive task | +| `python3 ./.trellis/scripts/get_context.py` | Get session context | + +--- + +## Platform Detection + +Trellis auto-detects your platform based on config directories. For Windsurf users, ensure detection works correctly: + +| Condition | Detected Platform | +|-----------|-------------------| +| Only `.windsurf/workflows/` exists and no other platform dirs are present | `windsurf` ✅ | +| `.windsurf/` exists alongside higher-priority platform dirs (for example `.claude/`) | Higher-priority platform wins | + +If auto-detection fails, set manually: + +```bash +export TRELLIS_PLATFORM=windsurf +``` + +Or prefix commands: + +```bash +TRELLIS_PLATFORM=windsurf python3 ./.trellis/scripts/task.py list +``` + +## Session End Reminder + +**IMPORTANT**: When a task or session is completed, remind the user: + +> Before ending this session, please run `/trellis-record-session` to record what we accomplished. diff --git a/packages/cli/src/templates/windsurf/workflows/trellis-update-spec.md b/packages/cli/src/templates/windsurf/workflows/trellis-update-spec.md new file mode 100644 index 0000000..2c72de5 --- /dev/null +++ b/packages/cli/src/templates/windsurf/workflows/trellis-update-spec.md @@ -0,0 +1,358 @@ +--- +description: Update the relevant code-spec documents with newly learned contracts and patterns. +--- + +# Update Code-Spec - Capture Executable Contracts + +When you learn something valuable (from debugging, implementing, or discussion), use this workflow to update the relevant code-spec documents. + +**Timing**: After completing a task, fixing a bug, or discovering a new pattern + +--- + +## Code-Spec First Rule (CRITICAL) + +In this project, "spec" for implementation work means **code-spec**: +- Executable contracts (not principle-only text) +- Concrete signatures, payload fields, env keys, and boundary behavior +- Testable validation/error behavior + +If the change touches infra or cross-layer contracts, code-spec depth is mandatory. + +### Mandatory Triggers + +Apply code-spec depth when the change includes any of: +- New/changed command or API signature +- Cross-layer request/response contract change +- Database schema/migration change +- Infra integration (storage, queue, cache, secrets, env wiring) + +### Mandatory Output (7 Sections) + +For triggered tasks, include all sections below: +1. Scope / Trigger +2. Signatures (command/API/DB) +3. Contracts (request/response/env) +4. Validation & Error Matrix +5. Good/Base/Bad Cases +6. Tests Required (with assertion points) +7. Wrong vs Correct (at least one pair) + +--- + +## When to Update Code-Specs + +| Trigger | Example | Target Spec | +|---------|---------|-------------| +| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file | +| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section | +| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` | +| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file | +| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section | +| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` | +| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) | + +**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely. + +--- + +## Spec Structure Overview + +``` +.trellis/spec/ +├── backend/ # Backend coding standards +│ ├── index.md # Overview and links +│ └── *.md # Topic-specific guidelines +├── frontend/ # Frontend coding standards +│ ├── index.md # Overview and links +│ └── *.md # Topic-specific guidelines +└── guides/ # Thinking checklists (NOT coding specs!) + ├── index.md # Guide index + └── *.md # Topic-specific guides +``` + +### CRITICAL: Code-Spec vs Guide - Know the Difference + +| Type | Location | Purpose | Content Style | +|------|----------|---------|---------------| +| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points | +| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs | + +**Decision Rule**: Ask yourself: + +- "This is **how to write** the code" → Put in `backend/` or `frontend/` +- "This is **what to consider** before writing" → Put in `guides/` + +**Example**: + +| Learning | Wrong Location | Correct Location | +|----------|----------------|------------------| +| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` | +| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` | + +**Guides should be short checklists that point to specs**, not duplicate the detailed rules. + +--- + +## Update Process + +### Step 1: Identify What You Learned + +Answer these questions: + +1. **What did you learn?** (Be specific) +2. **Why is it important?** (What problem does it prevent?) +3. **Where does it belong?** (Which spec file?) + +### Step 2: Classify the Update Type + +| Type | Description | Action | +|------|-------------|--------| +| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section | +| **Project Convention** | How we do X in this project | Add to relevant section with examples | +| **New Pattern** | A reusable approach discovered | Add to "Patterns" section | +| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section | +| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section | +| **Convention** | Agreed-upon standard | Add to relevant section | +| **Gotcha** | Non-obvious behavior | Add warning callout | + +### Step 3: Read the Target Code-Spec + +Before editing, read the current code-spec to: +- Understand existing structure +- Avoid duplicating content +- Find the right section for your update + +```bash +cat .trellis/spec/<category>/<file>.md +``` + +### Step 4: Make the Update + +Follow these principles: + +1. **Be Specific**: Include concrete examples, not just abstract rules +2. **Explain Why**: State the problem this prevents +3. **Show Contracts**: Add signatures, payload fields, and error behavior +4. **Show Code**: Add code snippets for key patterns +5. **Keep it Short**: One concept per section + +### Step 5: Update the Index (if needed) + +If you added a new section or the code-spec status changed, update the category's `index.md`. + +--- + +## Update Templates + +### Mandatory Template for Infra/Cross-Layer Work + +```markdown +## Scenario: <name> + +### 1. Scope / Trigger +- Trigger: <why this requires code-spec depth> + +### 2. Signatures +- Backend command/API/DB signature(s) + +### 3. Contracts +- Request fields (name, type, constraints) +- Response fields (name, type, constraints) +- Environment keys (required/optional) + +### 4. Validation & Error Matrix +- <condition> -> <error> + +### 5. Good/Base/Bad Cases +- Good: ... +- Base: ... +- Bad: ... + +### 6. Tests Required +- Unit/Integration/E2E with assertion points + +### 7. Wrong vs Correct +#### Wrong +... +#### Correct +... +``` + +### Adding a Design Decision + +```markdown +### Design Decision: [Decision Name] + +**Context**: What problem were we solving? + +**Options Considered**: +1. Option A - brief description +2. Option B - brief description + +**Decision**: We chose Option X because... + +**Example**: +\`\`\`typescript +// How it's implemented +code example +\`\`\` + +**Extensibility**: How to extend this in the future... +``` + +### Adding a Project Convention + +```markdown +### Convention: [Convention Name] + +**What**: Brief description of the convention. + +**Why**: Why we do it this way in this project. + +**Example**: +\`\`\`typescript +// How to follow this convention +code example +\`\`\` + +**Related**: Links to related conventions or specs. +``` + +### Adding a New Pattern + +```markdown +### Pattern Name + +**Problem**: What problem does this solve? + +**Solution**: Brief description of the approach. + +**Example**: +\`\`\` +// Good +code example + +// Bad +code example +\`\`\` + +**Why**: Explanation of why this works better. +``` + +### Adding a Forbidden Pattern + +```markdown +### Don't: Pattern Name + +**Problem**: +\`\`\` +// Don't do this +bad code example +\`\`\` + +**Why it's bad**: Explanation of the issue. + +**Instead**: +\`\`\` +// Do this instead +good code example +\`\`\` +``` + +### Adding a Common Mistake + +```markdown +### Common Mistake: Description + +**Symptom**: What goes wrong + +**Cause**: Why this happens + +**Fix**: How to correct it + +**Prevention**: How to avoid it in the future +``` + +### Adding a Gotcha + +```markdown +> **Warning**: Brief description of the non-obvious behavior. +> +> Details about when this happens and how to handle it. +``` + +--- + +## Interactive Mode + +If you're unsure what to update, answer these prompts: + +1. **What did you just finish?** + - [ ] Fixed a bug + - [ ] Implemented a feature + - [ ] Refactored code + - [ ] Had a discussion about approach + +2. **What did you learn or decide?** + - Design decision (why X over Y) + - Project convention (how we do X) + - Non-obvious behavior (gotcha) + - Better approach (pattern) + +3. **Would future AI/developers need to know this?** + - To understand how the code works → Yes, update spec + - To maintain or extend the feature → Yes, update spec + - To avoid repeating mistakes → Yes, update spec + - Purely one-off implementation detail → Maybe skip + +4. **Which area does it relate to?** + - [ ] Backend code + - [ ] Frontend code + - [ ] Cross-layer data flow + - [ ] Code organization/reuse + - [ ] Quality/testing + +--- + +## Quality Checklist + +Before finishing your code-spec update: + +- [ ] Is the content specific and actionable? +- [ ] Did you include a code example? +- [ ] Did you explain WHY, not just WHAT? +- [ ] Did you include executable signatures/contracts? +- [ ] Did you include validation and error matrix? +- [ ] Did you include Good/Base/Bad cases? +- [ ] Did you include required tests with assertion points? +- [ ] Is it in the right code-spec file? +- [ ] Does it duplicate existing content? +- [ ] Would a new team member understand it? + +--- + +## Relationship to Other Workflows + +``` +Development Flow: + Learn something → /trellis-update-spec → Knowledge captured + ↑ ↓ + /trellis-break-loop ←──────────────────── Future sessions benefit + (deep bug analysis) +``` + +- `/trellis-break-loop` - Analyzes bugs deeply, often reveals spec updates needed +- `/trellis-update-spec` - Actually makes the updates (this workflow) +- `/trellis-finish-work` - Reminds you to check if specs need updates + +--- + +## Core Philosophy + +> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.** + +The goal is **institutional memory**: +- What one person learns, everyone benefits from +- What AI learns in one session, persists to future sessions +- Mistakes become documented guardrails diff --git a/packages/cli/src/types/ai-tools.ts b/packages/cli/src/types/ai-tools.ts index a15a415..f122904 100644 --- a/packages/cli/src/types/ai-tools.ts +++ b/packages/cli/src/types/ai-tools.ts @@ -17,6 +17,7 @@ export type AITool = | "kiro" | "gemini" | "antigravity" + | "windsurf" | "qoder" | "codebuddy"; @@ -34,6 +35,7 @@ export type TemplateDir = | "kiro" | "gemini" | "antigravity" + | "windsurf" | "qoder" | "codebuddy"; @@ -51,6 +53,7 @@ export type CliFlag = | "kiro" | "gemini" | "antigravity" + | "windsurf" | "qoder" | "codebuddy"; @@ -163,6 +166,14 @@ export const AI_TOOLS: Record<AITool, AIToolConfig> = { defaultChecked: false, hasPythonHooks: false, }, + windsurf: { + name: "Windsurf", + templateDirs: ["common", "windsurf"], + configDir: ".windsurf/workflows", + cliFlag: "windsurf", + defaultChecked: false, + hasPythonHooks: false, + }, qoder: { name: "Qoder", templateDirs: ["common", "qoder"], diff --git a/packages/cli/test/commands/init.integration.test.ts b/packages/cli/test/commands/init.integration.test.ts index f5fd5e5..7437510 100644 --- a/packages/cli/test/commands/init.integration.test.ts +++ b/packages/cli/test/commands/init.integration.test.ts @@ -72,6 +72,9 @@ describe("init() integration", () => { expect(fs.existsSync(path.join(tmpDir, ".gemini"))).toBe(false); expect(fs.existsSync(path.join(tmpDir, ".qoder"))).toBe(false); expect(fs.existsSync(path.join(tmpDir, ".codebuddy"))).toBe(false); + expect(fs.existsSync(path.join(tmpDir, ".windsurf", "workflows"))).toBe( + false, + ); // Root files expect(fs.existsSync(path.join(tmpDir, "AGENTS.md"))).toBe(true); @@ -93,6 +96,9 @@ describe("init() integration", () => { expect(fs.existsSync(path.join(tmpDir, ".gemini"))).toBe(false); expect(fs.existsSync(path.join(tmpDir, ".qoder"))).toBe(false); expect(fs.existsSync(path.join(tmpDir, ".codebuddy"))).toBe(false); + expect(fs.existsSync(path.join(tmpDir, ".windsurf", "workflows"))).toBe( + false, + ); }); it("#3 multi platform creates all selected platform directories", async () => { @@ -111,6 +117,9 @@ describe("init() integration", () => { expect(fs.existsSync(path.join(tmpDir, ".gemini"))).toBe(false); expect(fs.existsSync(path.join(tmpDir, ".qoder"))).toBe(false); expect(fs.existsSync(path.join(tmpDir, ".codebuddy"))).toBe(false); + expect(fs.existsSync(path.join(tmpDir, ".windsurf", "workflows"))).toBe( + false, + ); }); it("#3b codex platform creates skills plus .codex assets", async () => { @@ -174,6 +183,21 @@ describe("init() integration", () => { expect(fs.existsSync(path.join(tmpDir, ".gemini"))).toBe(false); }); + it("#3f windsurf platform creates .windsurf/workflows", async () => { + await init({ yes: true, windsurf: true }); + + expect( + fs.existsSync(path.join(tmpDir, ".windsurf", "workflows")), + ).toBe(true); + expect( + fs.existsSync( + path.join(tmpDir, ".windsurf", "workflows", "trellis-start.md"), + ), + ).toBe(true); + expect(fs.existsSync(path.join(tmpDir, ".claude"))).toBe(false); + expect(fs.existsSync(path.join(tmpDir, ".cursor"))).toBe(false); + }); + it("#3g qoder platform creates .qoder/skills", async () => { await init({ yes: true, qoder: true }); diff --git a/packages/cli/test/configurators/index.test.ts b/packages/cli/test/configurators/index.test.ts index 5c43da9..1ec0009 100644 --- a/packages/cli/test/configurators/index.test.ts +++ b/packages/cli/test/configurators/index.test.ts @@ -68,6 +68,7 @@ describe("isManagedPath", () => { expect(isManagedPath(".codex/agents/check.toml")).toBe(true); expect(isManagedPath(".agent/workflows/start.md")).toBe(true); expect(isManagedPath(".kiro/skills/start/SKILL.md")).toBe(true); + expect(isManagedPath(".windsurf/workflows/trellis-start.md")).toBe(true); }); // Positive: exact match (startsWith(d + "/") = false, === d = true) @@ -80,6 +81,7 @@ describe("isManagedPath", () => { expect(isManagedPath(".codex")).toBe(true); expect(isManagedPath(".agent/workflows")).toBe(true); expect(isManagedPath(".kiro/skills")).toBe(true); + expect(isManagedPath(".windsurf/workflows")).toBe(true); expect(isManagedPath(".trellis")).toBe(true); }); @@ -99,6 +101,7 @@ describe("isManagedPath", () => { expect(isManagedPath(".codex-backup")).toBe(false); expect(isManagedPath(".agent/workflows-backup")).toBe(false); expect(isManagedPath(".kiro/skills-backup")).toBe(false); + expect(isManagedPath(".windsurf/workflows-backup")).toBe(false); }); // Boundary: empty string @@ -129,6 +132,7 @@ describe("isManagedPath", () => { expect(isManagedPath(".codex\\agents\\check.toml")).toBe(true); expect(isManagedPath(".agent\\workflows\\start.md")).toBe(true); expect(isManagedPath(".kiro\\skills\\start\\SKILL.md")).toBe(true); + expect(isManagedPath(".windsurf\\workflows\\trellis-start.md")).toBe(true); }); // Mixed separators diff --git a/packages/cli/test/configurators/platforms.test.ts b/packages/cli/test/configurators/platforms.test.ts index e4540a7..39da5be 100644 --- a/packages/cli/test/configurators/platforms.test.ts +++ b/packages/cli/test/configurators/platforms.test.ts @@ -17,6 +17,7 @@ import { getHooksConfig as getCodexHooksConfig, } from "../../src/templates/codex/index.js"; import { getAllWorkflows as getAllAntigravityWorkflows } from "../../src/templates/antigravity/index.js"; +import { getAllWorkflows as getAllWindsurfWorkflows } from "../../src/templates/windsurf/index.js"; import { getAllSkills as getAllKiroSkills } from "../../src/templates/kiro/index.js"; import { getAllCommands as getAllGeminiCommands } from "../../src/templates/gemini/index.js"; import { getAllSkills as getAllQoderSkills } from "../../src/templates/qoder/index.js"; @@ -87,6 +88,14 @@ describe("getConfiguredPlatforms", () => { expect(result.has("antigravity")).toBe(true); }); + it("detects .windsurf/workflows directory as windsurf", () => { + fs.mkdirSync(path.join(tmpDir, ".windsurf", "workflows"), { + recursive: true, + }); + const result = getConfiguredPlatforms(tmpDir); + expect(result.has("windsurf")).toBe(true); + }); + it("detects .kiro/skills directory as kiro", () => { fs.mkdirSync(path.join(tmpDir, ".kiro", "skills"), { recursive: true }); const result = getConfiguredPlatforms(tmpDir); @@ -341,6 +350,35 @@ describe("configurePlatform", () => { } }); + it("configurePlatform('windsurf') creates .windsurf/workflows directory", async () => { + await configurePlatform("windsurf", tmpDir); + expect(fs.existsSync(path.join(tmpDir, ".windsurf", "workflows"))).toBe( + true, + ); + }); + + it("configurePlatform('windsurf') writes all workflow templates", async () => { + await configurePlatform("windsurf", tmpDir); + + const expectedWorkflows = getAllWindsurfWorkflows(); + const expectedNames = expectedWorkflows.map((workflow) => workflow.name).sort(); + + const workflowsRoot = path.join(tmpDir, ".windsurf", "workflows"); + const actualNames = fs + .readdirSync(workflowsRoot, { withFileTypes: true }) + .filter((entry) => entry.isFile()) + .map((entry) => entry.name.replace(/\.md$/, "")) + .sort(); + + expect(actualNames).toEqual(expectedNames); + + for (const workflow of expectedWorkflows) { + const workflowPath = path.join(workflowsRoot, `${workflow.name}.md`); + expect(fs.existsSync(workflowPath)).toBe(true); + expect(fs.readFileSync(workflowPath, "utf-8")).toBe(workflow.content); + } + }); + it("configurePlatform('qoder') creates .qoder directory", async () => { await configurePlatform("qoder", tmpDir); expect(fs.existsSync(path.join(tmpDir, ".qoder"))).toBe(true); diff --git a/packages/cli/test/regression.test.ts b/packages/cli/test/regression.test.ts index 4db4ba9..8c44389 100644 --- a/packages/cli/test/regression.test.ts +++ b/packages/cli/test/regression.test.ts @@ -1066,6 +1066,11 @@ describe("regression: platform additions (beta.9, beta.13, beta.16)", () => { expect(AI_TOOLS.antigravity.configDir).toBe(".agent/workflows"); }); + it("[windsurf] Windsurf platform is registered", () => { + expect(AI_TOOLS).toHaveProperty("windsurf"); + expect(AI_TOOLS.windsurf.configDir).toBe(".windsurf/workflows"); + }); + it("[qoder] Qoder platform is registered", () => { expect(AI_TOOLS).toHaveProperty("qoder"); expect(AI_TOOLS.qoder.configDir).toBe(".qoder"); @@ -1132,6 +1137,11 @@ describe("regression: cli_adapter platform support (beta.9, beta.13, beta.16)", expect(commonCliAdapter).toContain(".agent"); }); + it("[windsurf] cli_adapter.py supports windsurf platform", () => { + expect(commonCliAdapter).toContain('"windsurf"'); + expect(commonCliAdapter).toContain(".windsurf"); + }); + it("[qoder] cli_adapter.py supports qoder platform", () => { expect(commonCliAdapter).toContain('"qoder"'); expect(commonCliAdapter).toContain(".qoder"); @@ -1162,6 +1172,7 @@ describe("regression: cli_adapter platform support (beta.9, beta.13, beta.16)", expect(commonCliAdapter).toContain(".kiro"); expect(commonCliAdapter).toContain(".gemini"); expect(commonCliAdapter).toContain(".agent"); + expect(commonCliAdapter).toContain(".windsurf"); expect(commonCliAdapter).toContain(".qoder"); expect(commonCliAdapter).toContain(".codebuddy"); }); @@ -1352,6 +1363,24 @@ describe("regression: collectTemplates paths match init directory structure (0.3 } }); + it("[windsurf] windsurf uses workflows/ instead of commands/trellis/", () => { + const templates = collectPlatformTemplates("windsurf"); + expect(templates).toBeInstanceOf(Map); + if (!templates) return; + const keys = [...templates.keys()]; + for (const key of keys) { + expect(key, `windsurf path should use workflows/: ${key}`).toContain( + ".windsurf/workflows/", + ); + expect(key, `windsurf file should use trellis- prefix: ${key}`).toContain( + ".windsurf/workflows/trellis-", + ); + expect(key, `windsurf should not use commands/: ${key}`).not.toContain( + "/commands/", + ); + } + }); + it("[codex] collectTemplates tracks both .agents skills and .codex assets", () => { const templates = collectPlatformTemplates("codex"); expect(templates).toBeInstanceOf(Map); diff --git a/packages/cli/test/templates/extract.test.ts b/packages/cli/test/templates/extract.test.ts index 5ab5d9b..75bcbcd 100644 --- a/packages/cli/test/templates/extract.test.ts +++ b/packages/cli/test/templates/extract.test.ts @@ -11,6 +11,7 @@ import { getKiroTemplatePath, getGeminiTemplatePath, getAntigravityTemplatePath, + getWindsurfTemplatePath, getQoderTemplatePath, getCodebuddyTemplatePath, getTrellisSourcePath, @@ -22,6 +23,7 @@ import { getKiroSourcePath, getGeminiSourcePath, getAntigravitySourcePath, + getWindsurfSourcePath, readTrellisFile, readTemplate, readScript, @@ -98,6 +100,12 @@ describe("template path functions", () => { expect(fs.statSync(p).isDirectory()).toBe(true); }); + it("getWindsurfTemplatePath returns existing directory", () => { + const p = getWindsurfTemplatePath(); + expect(fs.existsSync(p)).toBe(true); + expect(fs.statSync(p).isDirectory()).toBe(true); + }); + it("getQoderTemplatePath returns existing directory", () => { const p = getQoderTemplatePath(); expect(fs.existsSync(p)).toBe(true); @@ -151,6 +159,10 @@ describe("deprecated source path aliases", () => { it("getAntigravitySourcePath equals getAntigravityTemplatePath", () => { expect(getAntigravitySourcePath()).toBe(getAntigravityTemplatePath()); }); + + it("getWindsurfSourcePath equals getWindsurfTemplatePath", () => { + expect(getWindsurfSourcePath()).toBe(getWindsurfTemplatePath()); + }); }); // ============================================================================= diff --git a/packages/cli/test/templates/windsurf.test.ts b/packages/cli/test/templates/windsurf.test.ts new file mode 100644 index 0000000..7ac5566 --- /dev/null +++ b/packages/cli/test/templates/windsurf.test.ts @@ -0,0 +1,163 @@ +import { describe, expect, it } from "vitest"; +import { getAllWorkflows } from "../../src/templates/windsurf/index.js"; + +const EXPECTED_WORKFLOW_NAMES = [ + "trellis-before-dev", + "trellis-brainstorm", + "trellis-break-loop", + "trellis-check", + "trellis-check-cross-layer", + "trellis-create-command", + "trellis-finish-work", + "trellis-integrate-skill", + "trellis-onboard", + "trellis-record-session", + "trellis-start", + "trellis-update-spec", +]; + +describe("windsurf getAllWorkflows", () => { + it("returns the expected workflow set", () => { + const workflows = getAllWorkflows(); + const names = workflows.map((workflow) => workflow.name).sort(); + expect(names).toEqual([...EXPECTED_WORKFLOW_NAMES].sort()); + }); + + it("preserves workflow names from filenames", () => { + const workflows = getAllWorkflows(); + expect( + workflows.find((workflow) => workflow.name === "trellis-start"), + ).toBeDefined(); + }); + + it("each workflow has non-empty content", () => { + const workflows = getAllWorkflows(); + for (const workflow of workflows) { + expect(workflow.content.length).toBeGreaterThan(0); + } + }); + + it("adds windsurf frontmatter descriptions to every workflow", () => { + const workflows = getAllWorkflows(); + + for (const workflow of workflows) { + expect(workflow.content).toMatch(/^---\ndescription: .+\n---\n\n/); + } + }); + + it("does not duplicate the description as the first body sentence", () => { + const workflows = getAllWorkflows(); + const byName = new Map(workflows.map((workflow) => [workflow.name, workflow])); + + const countOccurrences = (content: string | undefined, text: string): number => + (content?.split(text).length ?? 1) - 1; + + expect( + countOccurrences( + byName.get("trellis-before-dev")?.content, + "Read the relevant development guidelines before starting your task.", + ), + ).toBe(1); + expect( + countOccurrences( + byName.get("trellis-check")?.content, + "Check whether the code you just wrote follows the development guidelines.", + ), + ).toBe(1); + expect( + countOccurrences( + byName.get("trellis-check")?.content, + "Check if the code you just wrote follows the development guidelines.", + ), + ).toBe(0); + expect( + countOccurrences( + byName.get("trellis-create-command")?.content, + "Create a new Windsurf workflow in `.windsurf/workflows/trellis-<workflow-name>.md` based on user requirements.", + ), + ).toBe(1); + expect( + countOccurrences( + byName.get("trellis-integrate-skill")?.content, + "Adapt and integrate a reusable skill into your project's development guidelines", + ), + ).toBe(1); + expect( + countOccurrences( + byName.get("trellis-start")?.content, + "Initialize your AI development session and begin working on tasks.", + ), + ).toBe(1); + expect( + countOccurrences( + byName.get("trellis-update-spec")?.content, + "When you learn something valuable", + ), + ).toBe(1); + }); + + it("adapts skill paths and trigger names to windsurf workflows", () => { + const workflows = getAllWorkflows(); + + for (const workflow of workflows) { + expect(workflow.content).not.toContain(".agents/skills/"); + expect(workflow.content).not.toContain("/trellis:"); + } + + const createCommand = workflows.find( + (w) => w.name === "trellis-create-command", + ); + expect(createCommand?.content).toContain("Windsurf workflow"); + expect(createCommand?.content).toContain( + ".windsurf/workflows/trellis-<workflow-name>.md", + ); + expect(createCommand?.content).toContain("/trellis-create-command"); + expect(createCommand?.content).toContain("/trellis-<workflow-name>"); + expect(createCommand?.content).not.toContain("$create-command"); + expect(createCommand?.content).not.toContain("open /skills and select it"); + + const start = workflows.find((w) => w.name === "trellis-start"); + expect(start?.content).toContain("/trellis-start"); + expect(start?.content).toContain("/trellis-record-session"); + + }); + + it("keeps workflow-oriented docs free of Codex skill scaffolding", () => { + const workflows = getAllWorkflows(); + + const createCommand = workflows.find( + (w) => w.name === "trellis-create-command", + ); + expect(createCommand?.content).not.toContain("SKILL.md"); + expect(createCommand?.content).not.toContain("Skill name"); + expect(createCommand?.content).not.toContain("Determine skill type"); + expect(createCommand?.content).not.toContain("Generate Skill Content"); + expect(createCommand?.content).not.toContain("Based on command type"); + expect(createCommand?.content).not.toContain("# Command Title"); + expect(createCommand?.content).not.toContain("Command description"); + + const start = workflows.find((w) => w.name === "trellis-start"); + expect(start?.content).not.toContain("brainstorm skill's Step 8"); + expect(start?.content).not.toContain("## Skills Reference"); + expect(start?.content).not.toContain("### User Skills"); + + const onboard = workflows.find((w) => w.name === "trellis-onboard"); + expect(onboard?.content).not.toContain("what each skill does and WHY"); + expect(onboard?.content).not.toContain("$before-*-dev"); + expect(onboard?.content).not.toContain("/trellis-finish-work` skill"); + expect(onboard?.content).not.toContain("what each command does and WHY"); + expect(onboard?.content).not.toContain("What the command actually does"); + expect(onboard?.content).not.toContain("/trellis-start` command reads"); + + const recordSession = workflows.find( + (w) => w.name === "trellis-record-session", + ); + expect(recordSession?.content).not.toContain("This skill should only be used"); + + const updateSpec = workflows.find((w) => w.name === "trellis-update-spec"); + expect(updateSpec?.content).not.toContain("use this skill"); + + const breakLoop = workflows.find((w) => w.name === "trellis-break-loop"); + expect(breakLoop?.content).not.toContain("use this skill"); + }); +});