trellis-herbivore 0.1.0

package/dist/templates/copilot/prompts/parallel.prompt.md

@@ -0,0 +1,204 @@
+---
+description: "Trellis Copilot prompt: Multi-Agent Pipeline Orchestrator"
+---
+
+# Multi-Agent Pipeline Orchestrator
+
+You are the Multi-Agent Pipeline Orchestrator Agent, running in the main repository, responsible for collaborating with users to manage parallel development tasks.
+
+## Role Definition
+
+- **You are in the main repository**, not in a worktree
+- **You don't write code directly** - code work is done by agents in worktrees
+- **You are responsible for planning and dispatching**: discuss requirements, create plans, configure context, start worktree agents
+- **Delegate complex analysis to research agent**: finding specs, analyzing code structure
+
+---
+
+## Operation Types
+
+Operations in this document are categorized as:
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
+| `[USER]` | Slash commands executed by user | User |
+
+---
+
+## Startup Flow
+
+### Step 1: Understand Trellis Workflow `[AI]`
+
+First, read the workflow guide to understand the development process:
+
+```bash
+cat .trellis/workflow.md  # Development process, conventions, and quick start guide
+```
+
+### Step 2: Get Current Status `[AI]`
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+### Step 3: Read Project Guidelines `[AI]`
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages  # Discover available spec layers
+cat .trellis/spec/guides/index.md    # Thinking guides
+```
+
+### Step 4: Ask User for Requirements
+
+Ask the user:
+
+1. What feature to develop?
+2. Which modules are involved?
+3. Development type? (backend / frontend / fullstack)
+
+---
+
+## Planning: Choose Your Approach
+
+Based on requirement complexity, choose one of these approaches:
+
+### Option A: Plan Agent (Recommended for complex features) `[AI]`
+
+Use when:
+- Requirements need analysis and validation
+- Multiple modules or cross-layer changes
+- Unclear scope that needs research
+
+```bash
+python3 ./.trellis/scripts/multi_agent/plan.py \
+  --name "<feature-name>" \
+  --type "<backend|frontend|fullstack>" \
+  --requirement "<user requirement description>"
+```
+
+Plan Agent will:
+1. Evaluate requirement validity (may reject if unclear/too large)
+2. Call research agent to analyze codebase
+3. Create and configure task directory
+4. Write prd.md with acceptance criteria
+5. Output ready-to-use task directory
+
+After plan.py completes, start the worktree agent:
+
+```bash
+python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR"
+```
+
+### Option B: Manual Configuration (For simple/clear features) `[AI]`
+
+Use when:
+- Requirements are already clear and specific
+- You know exactly which files are involved
+- Simple, well-scoped changes
+
+#### Step 1: Create Task Directory
+
+```bash
+# title is task description, --slug for task directory name
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>)
+```
+
+#### Step 2: Configure Task
+
+```bash
+# Initialize jsonl context files
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <dev_type>
+
+# Set branch and scope
+python3 ./.trellis/scripts/task.py set-branch "$TASK_DIR" feature/<name>
+python3 ./.trellis/scripts/task.py set-scope "$TASK_DIR" <scope>
+```
+
+#### Step 3: Add Context (optional: use research agent)
+
+```bash
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
+```
+
+#### Step 4: Update prd.md
+
+```bash
+# task.py create already created prd.md; edit it with requirements and acceptance criteria.
+$EDITOR "$TASK_DIR/prd.md"
+```
+
+Use this shape:
+
+```markdown
+# Feature: <name>
+
+## Goal
+...
+
+## Requirements
+- ...
+
+## Acceptance Criteria
+- [ ] ...
+```
+
+#### Step 5: Validate and Start
+
+```bash
+python3 ./.trellis/scripts/task.py validate "$TASK_DIR"
+python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR"
+```
+
+---
+
+## After Starting: Report Status
+
+Tell the user the agent has started and provide monitoring commands.
+
+---
+
+## User Available Commands `[USER]`
+
+The following slash commands are for users (not AI):
+
+| Command | Description |
+|---------|-------------|
+| `/` | Start Multi-Agent Pipeline (this command) |
+| `/` | Start normal development mode (single process) |
+| `/` | Record session progress |
+| `/` | Pre-completion checklist |
+
+---
+
+## Monitoring Commands (for user reference)
+
+Tell the user they can use these commands to monitor:
+
+```bash
+python3 ./.trellis/scripts/multi_agent/status.py                    # Overview
+python3 ./.trellis/scripts/multi_agent/status.py --log <name>       # View log
+python3 ./.trellis/scripts/multi_agent/status.py --watch <name>     # Real-time monitoring
+python3 ./.trellis/scripts/multi_agent/cleanup.py <branch>          # Cleanup worktree
+```
+
+---
+
+## Pipeline Phases
+
+The dispatch agent in worktree will automatically execute:
+
+1. implement �?Implement feature
+2. check �?Check code quality
+3. finish �?Final verification
+4. create-pr �?Create PR
+
+---
+
+## Core Rules
+
+- **Don't write code directly** - delegate to agents in worktree
+- **Don't execute git commit** - agent does it via create-pr action
+- **Delegate complex analysis to research** - finding specs, analyzing code structure
+- **All sub agents use opus model** - ensure output quality

package/dist/templates/copilot/prompts/record-session.prompt.md

@@ -0,0 +1,66 @@
+---
+description: "Trellis Copilot prompt: Method 1: Simple parameters"
+---
+
+[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
+
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
+
+---
+
+## Record Work Progress
+
+### Step 1: Get Context & Check Tasks
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode record
+```
+
+[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
+- Code committed? → Archive it (don't wait for PR)
+- All acceptance criteria met? → Archive it
+- Don't skip archiving just because `status` still says `planning` or `in_progress`
+
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
+
+### Step 2: One-Click Add Session
+
+```bash
+# Method 1: Simple parameters
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what was done"
+
+# Method 2: Pass detailed content via stdin
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash"
+| Feature | Description |
+|---------|-------------|
+| New API | Added user authentication endpoint |
+| Frontend | Updated login form |
+
+**Updated Files**:
+- `packages/api/modules/auth/router.ts`
+- `apps/web/modules/auth/components/login-form.tsx`
+EOF
+```
+
+**Auto-completes**:
+- [OK] Appends session to journal-N.md
+- [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
+- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
+- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
+
+---
+
+## Script Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
+| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
+| `python3 ./.trellis/scripts/task.py list` | List active tasks |

package/dist/templates/copilot/prompts/start.prompt.md

@@ -0,0 +1,63 @@
+---
+description: "Trellis Copilot prompt: Start Session"
+---
+
+# Start Session
+
+Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent context by following these steps (each one mirrors a section the hook would otherwise inject).
+
+---
+
+## Step 1: Current state
+Identity, git status, current task, active tasks, journal location.
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
+```
+
+If this output includes a line beginning `Trellis update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
+
+## Step 2: Workflow overview
+Phase Index + skill routing table + DO-NOT-skip rules.
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
+```
+
+Full guide in `.trellis/workflow.md` (read on demand).
+
+## Step 3: Guideline indexes
+Discover packages + spec layers, then read each relevant index file.
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode packages
+cat .trellis/spec/guides/index.md
+cat .trellis/spec/<package>/<layer>/index.md   # for each relevant layer
+```
+
+Index files list the specific guideline docs to read when you actually start coding.
+
+## Step 4: Decide next action
+From Step 1 you know the current task and status. Check the task directory:
+
+- **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
+- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
+- **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
+  ```bash
+  {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
+  ```
+- **No active task** → classify first. For simple conversation / small task, ask only whether this turn should create a Trellis task. For complex work, ask whether you may create a Trellis task and enter planning. If the user says no, skip Trellis for this session.
+
+---
+
+## Skill routing (quick reference)
+
+| User intent | Skill |
+|---|---|
+| New feature / unclear requirements | `trellis-brainstorm` |
+| About to write code | `trellis-before-dev` |
+| Done coding / quality check | `trellis-check` |
+| Stuck / fixed same bug multiple times | `trellis-break-loop` |
+| Learned something worth capturing | `trellis-update-spec` |
+
+Full rules + anti-rationalization table in `.trellis/workflow.md`.

package/dist/templates/copilot/prompts/update-spec.prompt.md

@@ -0,0 +1,358 @@
+---
+description: "Trellis Copilot prompt: Update Code-Spec - Capture Executable Contracts"
+---
+
+# Update Code-Spec - Capture Executable Contracts
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## Code-Spec First Rule (CRITICAL)
+
+In this project, "spec" for implementation work means **code-spec**:
+- Executable contracts (not principle-only text)
+- Concrete signatures, payload fields, env keys, and boundary behavior
+- Testable validation/error behavior
+
+If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+1. Scope / Trigger
+2. Signatures (command/API/DB)
+3. Contracts (request/response/env)
+4. Validation & Error Matrix
+5. Good/Base/Bad Cases
+6. Tests Required (with assertion points)
+7. Wrong vs Correct (at least one pair)
+
+---
+
+## When to Update Code-Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
+| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section |
+| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
+| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
+| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
+
+**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── backend/           # Backend coding standards
+�?  ├── index.md       # Overview and links
+�?  └── *.md           # Topic-specific guidelines
+├── frontend/          # Frontend coding standards
+�?  ├── index.md       # Overview and links
+�?  └── *.md           # Topic-specific guidelines
+└── guides/            # Thinking checklists (NOT coding specs!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Code-Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
+| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
+
+**Decision Rule**: Ask yourself:
+
+- "This is **how to write** the code" �?Put in `backend/` or `frontend/`
+- "This is **what to consider** before writing" �?Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | �?`guides/cross-platform-thinking-guide.md` | �?`backend/script-conventions.md` |
+| "Remember to check encoding when writing cross-platform code" | �?`backend/script-conventions.md` | �?`guides/cross-platform-thinking-guide.md` |
+
+**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Code-Spec
+
+Before editing, read the current code-spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Contracts**: Add signatures, payload fields, and error behavior
+4. **Show Code**: Add code snippets for key patterns
+5. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the code-spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Mandatory Template for Infra/Cross-Layer Work
+
+```markdown
+## Scenario: <name>
+
+### 1. Scope / Trigger
+- Trigger: <why this requires code-spec depth>
+
+### 2. Signatures
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 7. Wrong vs Correct
+#### Wrong
+...
+#### Correct
+...
+```
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works �?Yes, update spec
+   - To maintain or extend the feature �?Yes, update spec
+   - To avoid repeating mistakes �?Yes, update spec
+   - Purely one-off implementation detail �?Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your code-spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Did you include executable signatures/contracts?
+- [ ] Did you include validation and error matrix?
+- [ ] Did you include Good/Base/Bad cases?
+- [ ] Did you include required tests with assertion points?
+- [ ] Is it in the right code-spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something �?/ �?Knowledge captured
+       �?                                 �?
+  / ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/` - Analyzes bugs deeply, often reveals spec updates needed
+- `/` - Actually makes the updates (this command)
+- `/` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails