trellis-herbivore 0.1.0

package/dist/templates/codex/skills/before-dev/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: before-dev
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
+---
+
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Read current task artifacts**:
+   - `prd.md` for requirements and acceptance criteria
+   - `design.md` if present for technical design
+   - `implement.md` if present for execution order and validation plan
+
+2. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+3. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+   - Any spec/research paths referenced by the task artifacts
+
+4. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+5. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+6. **Always read shared guides**:
+   ```bash
+   cat .trellis/spec/guides/index.md
+   ```
+
+7. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

package/dist/templates/codex/skills/brainstorm/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: brainstorm
+description: "Guide requirements discovery for a Trellis task after task-creation consent. Use when the user is ready to clarify requirements before implementation."
+---
+
+# Trellis Brainstorm
+
+## Non-Negotiable Interview Contract
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+## Non-Negotiable Evidence Rule
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
+
+Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
+
+---
+
+Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
+
+## Preconditions
+
+Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
+
+If no task exists yet, create one:
+
+```bash
+TASK_DIR=$({{PYTHON_CMD}} ./.trellis/scripts/task.py create "<short task title>" --slug <slug>)
+```
+
+Use a concise title from the user's request. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
+
+`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
+
+## Planning Flow
+
+1. Capture the user's request and initial known facts in `prd.md`.
+2. Inspect available evidence before asking questions:
+   - code, tests, fixtures, and configs
+   - README files, docs, existing specs, and domain notes
+   - related Trellis tasks, research files, and session history when present
+3. Separate what you found into:
+   - confirmed facts
+   - product intent still needed from the user
+   - scope or risk decisions still needed from the user
+   - likely out-of-scope items
+4. Ask the single highest-value remaining question.
+5. Include your recommended answer with the question.
+6. After each user answer, update `prd.md` before continuing.
+7. For complex tasks, create or update `design.md` and `implement.md` before implementation starts.
+
+Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
+
+## Question Rules
+
+Ask only one question per message.
+
+Each question must include:
+
+- the decision needed
+- why the answer matters
+- your recommended answer
+- the trade-off if the user chooses differently
+
+Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
+
+## Artifact Rules
+
+`prd.md` records requirements and acceptance:
+
+- goal and user value
+- confirmed facts
+- requirements
+- acceptance criteria
+- out of scope
+- open questions that still block planning
+
+`design.md` records technical design for complex tasks:
+
+- architecture and boundaries
+- data flow and contracts
+- compatibility and migration notes
+- important trade-offs
+- operational or rollback considerations
+
+`implement.md` records execution planning for complex tasks:
+
+- ordered implementation checklist
+- validation commands
+- risky files or rollback points
+- follow-up checks before `task.py start`
+
+Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
+
+`implement.md` is not a replacement for `implement.jsonl`. Use JSONL files only for manifest-style spec and research references when the task needs them.
+
+## Quality Bar
+
+Before declaring planning ready:
+
+- `prd.md` contains testable acceptance criteria.
+- Repository-answerable questions have already been answered through inspection.
+- Remaining open questions are genuinely about user intent or scope.
+- Complex tasks have `design.md` and `implement.md`.
+- The user has reviewed the final planning artifacts or explicitly approved proceeding.
+
+Do not start implementation until the user approves or asks for implementation.

package/dist/templates/codex/skills/break-loop/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: break-loop
+description: "Deep post-fix bug analysis across five dimensions: root cause categorization, fix failure analysis, prevention mechanisms, systematic expansion, and knowledge capture. Updates .trellis/spec/ guides with lessons learned to prevent recurring bugs. Use when a debugging session completes, after fixing a tricky bug, when the same class of bug keeps recurring, or when you want to capture debugging insights into project documentation."
+---
+
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this skill 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 skills 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/codex/skills/check/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: check
+description: "Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes."
+---
+
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Task Artifacts and Applicable Specs
+
+Read the current task artifacts in order:
+
+- `prd.md`
+- `design.md` if present
+- `implement.md` if present
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist
+
+### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+### Test Coverage
+
+- [ ] New function → unit test added?
+- [ ] Bug fix → regression test added?
+- [ ] Changed behavior → existing tests updated?
+
+### Spec Sync
+
+- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report violations found and fix them directly. Re-run project checks after fixes.

package/dist/templates/codex/skills/check-cross-layer/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: check-cross-layer
+description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
+---
+
+# 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 |
+| **`$check-cross-layer`** (this skill) | 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/codex/skills/create-command/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: create-command
+description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
+---
+
+# Create New Skill
+
+Create a new Codex skill in `.agents/skills/<skill-name>/SKILL.md` based on user requirements.
+
+## Usage
+
+```bash
+$create-command <skill-name> <description>
+```
+
+**Example**:
+```bash
+$create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Skill name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the skill should accomplish
+
+### 2. Analyze Requirements
+
+Determine skill 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 or code templates
+
+### 3. Generate Skill Content
+
+Minimum `SKILL.md` structure:
+
+```markdown
+---
+name: <skill-name>
+description: "<description>"
+---
+
+# <Skill Title>
+
+<Instructions for when and how to use this skill>
+```
+
+### 4. Create Files
+
+Create:
+- `.agents/skills/<skill-name>/SKILL.md`
+
+### 5. Confirm Creation
+
+Output result:
+
+```text
+[OK] Created Skill: <skill-name>
+
+File path:
+- .agents/skills/<skill-name>/SKILL.md
+
+Usage:
+- Trigger directly with $<skill-name>
+- Or open /skills and select it
+
+Description:
+<description>
+```
+
+## Skill Content Guidelines
+
+### [OK] Good skill 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 skill should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar skill exists first
+
+## Naming Conventions
+
+| Skill 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` |