@mindfoldhq/trellis 0.3.0-rc.5 → 0.3.0

package/dist/templates/gemini/commands/trellis/break-loop.toml

@@ -0,0 +1,129 @@
+description = "Deep bug analysis to break the fix-forget-repeat cycle"
+
+prompt = """
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command 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 commands 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.
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue -> update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue -> update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue -> update `code-reuse-thinking-guide.md`
+   - If it's domain-specific -> update `backend/*.md` or `frontend/*.md`
+
+2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+
+3. **Commit the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**
+"""

package/dist/templates/gemini/commands/trellis/check-backend.toml

@@ -0,0 +1,17 @@
+description = "Check if your code follows the backend development guidelines"
+
+prompt = """
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes -> `.trellis/spec/backend/database-guidelines.md`
+   - Error handling -> `.trellis/spec/backend/error-handling.md`
+   - Logging changes -> `.trellis/spec/backend/logging-guidelines.md`
+   - Type changes -> `.trellis/spec/backend/type-safety.md`
+   - Any changes -> `.trellis/spec/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found
+"""

package/dist/templates/gemini/commands/trellis/check-cross-layer.toml

@@ -0,0 +1,147 @@
+description = "Cross-layer verification check for multi-dimension changes"
+
+prompt = """
+# 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 **before** writing code.
+
+---
+
+## 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/gemini/commands/trellis/check-frontend.toml

@@ -0,0 +1,17 @@
+description = "Check if your code follows the frontend development guidelines"
+
+prompt = """
+Check if the code you just wrote follows the frontend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/frontend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Component changes -> `.trellis/spec/frontend/component-guidelines.md`
+   - Hook changes -> `.trellis/spec/frontend/hook-guidelines.md`
+   - State changes -> `.trellis/spec/frontend/state-management.md`
+   - Type changes -> `.trellis/spec/frontend/type-safety.md`
+   - Any changes -> `.trellis/spec/frontend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found
+"""

package/dist/templates/gemini/commands/trellis/create-command.toml

@@ -0,0 +1,119 @@
+description = "Create a new slash command in the Gemini CLI commands directory"
+
+prompt = """
+# Create New Slash Command
+
+Create a new slash command in `.gemini/commands/trellis/` directory based on user requirements.
+
+## Usage
+
+```
+/trellis:create-command <command-name> <description>
+```
+
+**Example**:
+```
+/trellis:create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Command name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the command should accomplish
+
+### 2. Analyze Requirements
+
+Determine command 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 Command Content
+
+Based on command type, generate appropriate TOML content:
+
+**Simple command**:
+```toml
+description = "Short description"
+
+prompt = \"\"\"
+Concise instruction describing what to do
+\"\"\"
+```
+
+**Complex command** (with steps):
+```toml
+description = "Short description"
+
+prompt = \"\"\"
+# Command Title
+
+Command description
+
+## Steps
+
+### 1. First Step
+Specific action
+
+### 2. Second Step
+Specific action
+
+## Output Format (if needed)
+
+Template
+\"\"\"
+```
+
+### 4. Create File
+
+Create the TOML file:
+- `.gemini/commands/trellis/<command-name>.toml`
+
+### 5. Confirm Creation
+
+Output result:
+```
+[OK] Created Slash Command: /trellis:<command-name>
+
+File path:
+- .gemini/commands/trellis/<command-name>.toml
+
+Usage:
+/trellis:<command-name>
+
+Description:
+<description>
+```
+
+## Command Content Guidelines
+
+### [OK] Good command 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 command should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar command exists first
+
+## Naming Conventions
+
+| Command Type | Prefix | Example |
+|--------------|--------|---------|
+| Session Start | `start` | `start` |
+| Pre-development | `before-` | `before-frontend-dev` |
+| Check | `check-` | `check-frontend` |
+| Record | `record-` | `record-session` |
+| Generate | `generate-` | `generate-api-doc` |
+| Update | `update-` | `update-changelog` |
+| Other | Verb-first | `review-code`, `sync-data` |
+"""

package/dist/templates/gemini/commands/trellis/finish-work.toml

@@ -0,0 +1,133 @@
+description = "Pre-commit checklist to ensure work completeness before submitting"
+
+prompt = """
+# 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. Documentation Sync
+
+**Structure 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 spec doc.
+
+### 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 |
+|-----------|-------------|-------|
+| Structure docs not updated | Others don't know the change | Check .trellis/spec/ |
+| 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 command)
+- `/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/gemini/commands/trellis/integrate-skill.toml

@@ -0,0 +1,104 @@
+description = "Adapt and integrate an external skill into project development guidelines"
+
+prompt = """
+# Integrate Skill into Project Guidelines
+
+Adapt and integrate an external skill into your project's development guidelines (not directly into project code).
+
+## 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 definition. If the skill doesn't exist, prompt user to check available skills.
+
+### 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`.
+
+#### 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`.
+
+### 5. Generate Integration Report
+
+Report:
+- Skill description and integration target
+- Tech stack compatibility
+- Integration locations (files modified)
+- Dependencies needed (if any)
+- Completed changes checklist
+
+---
+
+## 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) |
+"""