@mindfoldhq/trellis 0.4.0-beta.8 → 0.4.0-beta.9

package/dist/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

package/dist/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/<package>/<layer>/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.

package/dist/templates/windsurf/workflows/trellis-create-command.md

@@ -0,0 +1,154 @@
+---
+description: Create a new Windsurf workflow in `.windsurf/workflows/trellis-<workflow-name>.md` based on user requirements.
+---
+
+# Create New Workflow
+
+## Usage
+
+```
+/trellis-create-command <workflow-name> <description>
+```
+
+**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-<workflow-name>.md`
+
+### 5. Confirm Creation
+
+Output result:
+```
+[OK] Created Workflow: /trellis-<workflow-name>
+
+File paths:
+- .windsurf/workflows/trellis-<workflow-name>.md
+
+Usage:
+/trellis-<workflow-name>
+
+Description:
+<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]
+```

package/dist/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

package/dist/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 <skill-name>
+```
+
+**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/<skill-name>/`
+> - 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-<skill-name>
+## # <Skill Name> 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/<skill-name>/`
+
+@@@/section:skill-<skill-name>
+```
+
+#### 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/
+        +-- <skill-name>/
+            |-- README.md               # Example documentation
+            |-- example-1.ts.template   # Code example (use .template suffix)
+            +-- example-2.tsx.template
+```
+
+**File naming conventions**:
+- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`)
+- Config files: `<name>.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-related task> | <Section name> | `skill-<skill-name>` |
+```
+
+### 5. Generate Integration Report
+
+---
+
+## Skill Integration Report: `<skill-name>`
+
+### # 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-<name>`) |
+| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` |
+| 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 <package>
+# or
+pnpm add <package>
+# or
+yarn add <package>
+```
+
+### [OK] Completed Changes
+
+- [ ] Added `@@@section:skill-<name>` section to `doc.md`
+- [ ] Added index entry to `index.md`
+- [ ] Created example files in `examples/skills/<name>/`
+- [ ] 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-<skill-name> Use <skill-name> 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
+```