@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.1

package/dist/templates/windsurf/workflows/trellis-break-loop.md

@@ -1,111 +0,0 @@
----
-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.

package/dist/templates/windsurf/workflows/trellis-check-cross-layer.md

@@ -1,157 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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

@@ -1,154 +0,0 @@
----
-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

@@ -1,147 +0,0 @@
----
-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