@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.1

package/dist/templates/claude/commands/trellis/check-cross-layer.md

@@ -1,153 +0,0 @@
-# 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/claude/commands/trellis/check.md

@@ -1,25 +0,0 @@
-Check if 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/claude/commands/trellis/create-command.md

@@ -1,154 +0,0 @@
-# Create New Slash Command
-
-Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories 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 content:
-
-**Simple command** (1-3 lines):
-```markdown
-Concise instruction describing what to do
-```
-
-**Complex command** (with steps):
-```markdown
-# Command Title
-
-Command description
-
-## Steps
-
-### 1. First Step
-Specific action
-
-### 2. Second Step
-Specific action
-
-## Output Format (if needed)
-
-Template
-```
-
-### 4. Create Files
-
-Create in both directories:
-- `.cursor/commands/trellis-<command-name>.md`
-- `.claude/commands/trellis/<command-name>.md`
-
-### 5. Confirm Creation
-
-Output result:
-```
-[OK] Created Slash Command: /<command-name>
-
-File paths:
-- .cursor/commands/trellis-<command-name>.md
-- .claude/commands/trellis/<command-name>.md
-
-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-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 Command 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/claude/commands/trellis/finish-work.md

@@ -1,153 +0,0 @@
-# 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?
-
-### 1.5. Test Coverage
-
-Check if your change needs new or updated tests (see `.trellis/spec/unit-test/conventions.md`):
-
-- [ ] New pure function → unit test added?
-- [ ] Bug fix → regression test added in `test/regression.test.ts`?
-- [ ] Changed init/update behavior → integration test added/updated?
-- [ ] No logic change (text/data only) → no test needed
-
-### 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**:
-In pipeline mode, the finish agent will automatically detect and execute spec updates when gaps are found.
-If running this checklist manually, ensure spec sync is complete before committing — run `/trellis:update-spec` if needed.
-
-### 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 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/claude/commands/trellis/integrate-skill.md

@@ -1,219 +0,0 @@
-# Integrate Claude Skill into Project Guidelines
-
-Adapt and integrate a Claude global 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
-
-```bash
-openskills read <skill-name>
-```
-
-If the skill doesn't exist, prompt user to check available skills:
-```bash
-# Available skills are listed in AGENTS.md under <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`:
-
-```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 Usage Command
-
-If this skill is frequently used, create a shortcut command:
-
-```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
-```