@mindfoldhq/trellis 0.4.0-beta.8 → 0.4.0-rc.0

package/dist/templates/copilot/prompts/check-cross-layer.prompt.md

@@ -0,0 +1,157 @@
+---
+description: "Trellis Copilot prompt: Cross-Layer Check"
+---
+
+# 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 |
+| **`/`** (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/copilot/prompts/check.prompt.md

@@ -0,0 +1,29 @@
+---
+description: "Trellis Copilot prompt: check.prompt"
+---
+
+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/copilot/prompts/create-command.prompt.md

@@ -0,0 +1,116 @@
+---
+description: "Trellis Copilot prompt: Create New Copilot Prompt"
+---
+
+# Create New Copilot Prompt
+
+Create a new Copilot slash-command prompt file in `.github/prompts/`.
+
+## Usage
+
+```
+/create-command <command-name> <description>
+```
+
+Example:
+
+```
+/create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- Command name: must be kebab-case (example: `review-pr`)
+- Description: one-sentence purpose
+
+### 2. Analyze Requirements
+
+Classify the command intent:
+- Initialization
+- Pre-development check
+- Quality check
+- Session recording
+- Generation / automation
+
+### 3. Generate Prompt Content
+
+Create concise, executable Markdown content.
+
+Simple prompt shape:
+
+```markdown
+Single clear instruction with expected output.
+```
+
+Complex prompt shape:
+
+```markdown
+# Prompt Title
+
+Short purpose.
+
+## Steps
+
+### 1. Step One
+Concrete action.
+
+### 2. Step Two
+Concrete action.
+
+## Output
+
+Expected output format.
+```
+
+### 4. Create Prompt File
+
+Write file:
+
+- `.github/prompts/<command-name>.prompt.md`
+
+If the file already exists, compare content and update only when user asks to overwrite.
+
+### 5. Confirm Result
+
+Output:
+
+```
+[OK] Created Copilot Prompt: /<command-name>
+
+File path:
+- .github/prompts/<command-name>.prompt.md
+
+Usage:
+/<command-name>
+
+Description:
+<description>
+```
+
+## Content Quality Guidelines
+
+Good prompt traits:
+1. Clear and concise
+2. Actionable without extra interpretation
+3. Properly scoped
+4. Defines expected output when needed
+
+Avoid:
+1. Vague intent (example: "optimize code")
+2. Overly long instructions with mixed goals
+3. Duplicating existing prompt behavior without reason
+
+## Naming Conventions
+
+| Prompt 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` |

package/dist/templates/copilot/prompts/finish-work.prompt.md

@@ -0,0 +1,157 @@
+---
+description: "Trellis Copilot prompt: Finish Work - Pre-Commit Checklist"
+---
+
+# 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 `/` 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 -> / -> git commit -> /
+                          |                              |
+                   Ensure completeness              Record progress
+                   
+Debug Flow:
+  Hit bug -> Fix -> / -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `/` - Check work completeness (this command)
+- `/` - Record session and commits
+- `/` - 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/copilot/prompts/integrate-skill.prompt.md

@@ -0,0 +1,223 @@
+---
+description: "Trellis Copilot prompt: Integrate Claude Skill into Project Guidelines"
+---
+
+# 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
+
+```
+/ <skill-name>
+```
+
+**Examples**:
+```
+/ frontend-design
+/ 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
+/ 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
+```