@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.10

package/dist/templates/codebuddy/commands/trellis/start.md

@@ -1,373 +0,0 @@
-# Start Session
-
-Initialize your AI development session and begin working on tasks.
-
----
-
-## Operation Types
-
-Operations in this document are categorized as:
-
-| Marker | Meaning | Executor |
-|--------|---------|----------|
-| `[AI]` | Bash scripts or file reads executed by AI | You (AI) |
-| `[USER]` | Slash commands executed by user | User |
-
----
-
-## Initialization
-
-### 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
-```
-
-This returns:
-- Developer identity
-- Git status (branch, uncommitted changes)
-- Recent commits
-- Active tasks
-- Journal file status
-
-### Step 3: Read Guidelines Index `[AI]`
-
-```bash
-python3 ./.trellis/scripts/get_context.py --mode packages
-```
-
-This shows available packages and their spec layers. Read the relevant spec indexes:
-
-```bash
-cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
-cat .trellis/spec/guides/index.md              # Thinking guides (always read)
-```
-
-> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
-> At this step, just read the indexes to understand what's available.
-> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
-
-### Step 4: Check Active Tasks `[AI]`
-
-```bash
-python3 ./.trellis/scripts/task.py list
-```
-
-If continuing previous work, review the task file.
-
-### Step 5: Report Ready Status and Ask for Tasks
-
-Output a summary:
-
-```markdown
-## Session Initialized
-
-| Item | Status |
-|------|--------|
-| Developer | {name} |
-| Branch | {branch} |
-| Uncommitted | {count} file(s) |
-| Journal | {file} ({lines}/2000 lines) |
-| Active Tasks | {count} |
-
-Ready for your task. What would you like to work on?
-```
-
----
-
-## Task Classification
-
-When user describes a task, classify it:
-
-| Type | Criteria | Workflow |
-|------|----------|----------|
-| **Question** | User asks about code, architecture, or how something works | Answer directly |
-| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
-| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow |
-| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
-
-### Decision Rule
-
-> **If in doubt, use Brainstorm + Task Workflow.**
->
-> Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code.
-> The overhead is minimal, but the benefit is significant.
-
-> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
-> consider creating subtasks using `--parent` flag or `add-subtask` command.
-> See `/trellis:brainstorm` Step 8 for details.
-
----
-
-## Question / Trivial Fix
-
-For questions or trivial fixes, work directly:
-
-1. Answer question or make the fix
-2. If code was changed, remind user to run `/trellis:finish-work`
-
----
-
-## Simple Task
-
-For simple, well-defined tasks:
-
-1. Quick confirm: "I understand you want to [goal]. Shall I proceed?"
-2. If no, clarify and confirm again
-3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.**
-   - Create task directory (Phase 1 Path B, Step 2)
-   - Write PRD (Step 3)
-   - Research codebase (Phase 2, Step 5)
-   - Configure context (Step 6)
-   - Activate task (Step 7)
-   - Implement (Phase 3, Step 8)
-   - Check quality (Step 9)
-   - Complete (Step 10)
-
----
-
-## Complex Task - Brainstorm First
-
-For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation. Use `/trellis:brainstorm`.
-
-Summary:
-
-1. **Acknowledge and classify** - State your understanding
-2. **Create task directory** - Track evolving requirements in `prd.md`
-3. **Ask questions one at a time** - Update PRD after each answer
-4. **Propose approaches** - For architectural decisions
-5. **Confirm final requirements** - Get explicit approval
-6. **Proceed to Task Workflow** - With clear requirements in PRD
-
----
-
-## Task Workflow (Development Tasks)
-
-**Why this workflow?**
-- Run a dedicated research pass before coding
-- Configure specs in jsonl context files
-- Implement using injected context
-- Verify with a separate check pass
-- Result: Code that follows project conventions automatically
-
-### Overview: Two Entry Points
-
-```
-From Brainstorm (Complex Task):
-  PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete
-
-From Simple Task:
-  Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete
-```
-
-**Key principle: Research happens AFTER requirements are clear (PRD exists).**
-
----
-
-### Phase 1: Establish Requirements
-
-#### Path A: From Brainstorm (skip to Phase 2)
-
-PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
-
-#### Path B: From Simple Task
-
-**Step 1: Confirm Understanding** `[AI]`
-
-Quick confirm:
-- What is the goal?
-- What type of development? (frontend / backend / fullstack)
-- Any specific requirements or constraints?
-
-If unclear, ask clarifying questions.
-
-**Step 2: Create Task Directory** `[AI]`
-
-```bash
-TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)
-```
-
-**Step 3: Write PRD** `[AI]`
-
-Create `prd.md` in the task directory with:
-
-```markdown
-# <Task Title>
-
-## Goal
-<What we're trying to achieve>
-
-## Requirements
-- <Requirement 1>
-- <Requirement 2>
-
-## Acceptance Criteria
-- [ ] <Criterion 1>
-- [ ] <Criterion 2>
-
-## Technical Notes
-<Any technical decisions or constraints>
-```
-
----
-
-### Phase 2: Prepare for Implementation (shared)
-
-> Both paths converge here. PRD and task directory must exist before proceeding.
-
-**Step 4: Code-Spec Depth Check** `[AI]`
-
-If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
-
-Trigger this requirement when the change includes any of:
-- New or changed command/API signatures
-- Database schema or migration changes
-- Infra integrations (storage, queue, cache, secrets, env contracts)
-- Cross-layer payload transformations
-
-Must-have before proceeding:
-- [ ] Target code-spec files to update are identified
-- [ ] Concrete contract is defined (signature, fields, env keys)
-- [ ] Validation and error matrix is defined
-- [ ] At least one Good/Base/Bad case is defined
-
-**Step 5: Research the Codebase** `[AI]`
-
-Based on the confirmed PRD, run a focused research pass and produce:
-
-1. Relevant spec files in `.trellis/spec/`
-2. Existing code patterns to follow (2-3 examples)
-3. Files that will likely need modification
-
-Use this output format:
-
-```markdown
-## Relevant Specs
-- <path>: <why it's relevant>
-
-## Code Patterns Found
-- <pattern>: <example file path>
-
-## Files to Modify
-- <path>: <what change>
-```
-
-**Step 6: Configure Context** `[AI]`
-
-Initialize default context:
-
-```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
-# type: backend | frontend | fullstack
-```
-
-Add specs found in your research pass:
-
-```bash
-# For each relevant spec and code pattern:
-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 7: Activate Task** `[AI]`
-
-```bash
-python3 ./.trellis/scripts/task.py start "$TASK_DIR"
-```
-
-This sets `.current-task` so hooks can inject context.
-
----
-
-### Phase 3: Execute (shared)
-
-**Step 8: Implement** `[AI]`
-
-Implement the task described in `prd.md`.
-
-- Follow all specs injected into implement context
-- Keep changes scoped to requirements
-- Run lint and typecheck before finishing
-
-**Step 9: Check Quality** `[AI]`
-
-Run a quality pass against check context:
-
-- Review all code changes against the specs
-- Fix issues directly
-- Ensure lint and typecheck pass
-
-**Step 10: Complete** `[AI]`
-
-1. Verify lint and typecheck pass
-2. Report what was implemented
-3. Remind user to:
-   - Test the changes
-   - Commit when ready
-   - Run `/trellis:record-session` to record this session
-
----
-
-## User Available Commands `[USER]`
-
-The following slash commands are for users (not AI):
-
-| Command | Description |
-|---------|-------------|
-| `/trellis:start` | Start development session (this command) |
-| `/trellis:brainstorm` | Clarify vague requirements before implementation |
-| `/trellis:before-dev` | Read development guidelines |
-| `/trellis:check` | Check code quality |
-| `/trellis:check-cross-layer` | Cross-layer verification |
-| `/trellis:finish-work` | Pre-commit checklist |
-| `/trellis:record-session` | Record session progress |
-
----
-
-## AI Executed Scripts `[AI]`
-
-| Script | Purpose |
-|--------|---------|
-| `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create task directory |
-| `python3 ./.trellis/scripts/task.py list` | List active tasks |
-| `python3 ./.trellis/scripts/task.py archive <name>` | Archive task |
-| `python3 ./.trellis/scripts/get_context.py` | Get session context |
-
----
-
-## Platform Detection
-
-Trellis auto-detects your platform based on config directories. For CodeBuddy users, ensure detection works correctly:
-
-| Condition | Detected Platform |
-|-----------|-------------------|
-| Only `.codebuddy/` exists | `codebuddy` ✅ |
-| Both `.codebuddy/` and `.claude/` exist | `claude` (default) |
-
-If auto-detection fails, set manually:
-
-```bash
-export TRELLIS_PLATFORM=codebuddy
-```
-
-Or prefix commands:
-
-```bash
-TRELLIS_PLATFORM=codebuddy python3 ./.trellis/scripts/task.py list
-```
-
----
-
-## Session End Reminder
-
-**IMPORTANT**: When a task or session is completed, remind the user:
-
-> Before ending this session, please run `/trellis:record-session` to record what we accomplished.

package/dist/templates/codex/agents/check.toml

@@ -1,23 +0,0 @@
-name = "check"
-description = "Read-only Trellis reviewer focused on correctness, missing tests, and spec drift."
-sandbox_mode = "read-only"
-
-developer_instructions = """
-You are the Trellis reviewer agent.
-
-Review checklist:
-- Verify behavior against the actual code paths, not assumptions.
-- Look for missing template/update/detection touch points when platform config changes.
-- Check whether tests should be added or updated.
-- Check whether `.trellis/spec/` docs need sync after implementation.
-- Prefer concrete findings over speculative warnings.
-
-Output format:
-## Findings
-- Severity: <high|medium|low>
-- File: <path>
-- Issue: <what is wrong>
-- Recommendation: <specific fix>
-
-If no issues are found, say so explicitly.
-"""

package/dist/templates/codex/agents/research.toml

@@ -1,26 +0,0 @@
-name = "research"
-description = "Read-only Trellis researcher for specs, code patterns, and affected files."
-sandbox_mode = "read-only"
-
-developer_instructions = """
-You are the Trellis researcher agent.
-
-Responsibilities:
-- Read `.trellis/workflow.md`, relevant `.trellis/spec/` files, and target code before proposing changes.
-- Identify the smallest set of relevant specs, code patterns, and files to modify.
-- Call out cross-layer or cross-platform risks when they are real.
-- Do not edit files.
-
-Output format:
-## Relevant Specs
-- <path>: <why>
-
-## Code Patterns Found
-- <pattern>: <file>
-
-## Files to Modify
-- <path>: <change>
-
-## Risks / Follow-ups
-- <none or concrete note>
-"""

package/dist/templates/codex/codex-skills/parallel/SKILL.md

@@ -1,194 +0,0 @@
----
-name: parallel
-description: "Multi-agent pipeline orchestrator that plans and dispatches parallel development tasks to worktree agents. Reads project context, configures task directories with PRDs and jsonl context files, and launches isolated coding agents. Use when multiple independent features need parallel development, orchestrating worktree agents, or managing multi-agent coding pipelines."
----
-
-# 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**: find specs, inspect code structure, and reduce ambiguity before dispatch
-
----
-
-## Operation Types
-
-Operations in this document are categorized as:
-
-| Marker | Meaning | Executor |
-|--------|---------|----------|
-| `[AI]` | Bash scripts or tool calls executed by AI | You (AI) |
-| `[USER]` | Skills 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>" \
-  --platform codex
-```
-
-Plan Agent will:
-1. Evaluate requirement validity (may reject if unclear/too large)
-2. Analyze the codebase and specs
-3. Create and configure task directory
-4. Write `prd.md` with acceptance criteria
-5. Output a ready-to-use task directory
-
-After `plan.py` completes, start the worktree agent:
-
-```bash
-python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR" --platform codex
-```
-
-### Option B: Manual Configuration (For simple or already-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
-TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>)
-```
-
-#### Step 2: Configure Task
-
-```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <dev_type>
-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
-
-```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: Create `prd.md`
-
-```bash
-cat > "$TASK_DIR/prd.md" << 'END_PRD'
-# Feature: <name>
-
-## Requirements
-- ...
-
-## Acceptance Criteria
-- ...
-END_PRD
-```
-
-#### Step 5: Validate and Start
-
-```bash
-python3 ./.trellis/scripts/task.py validate "$TASK_DIR"
-python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR" --platform codex
-```
-
----
-
-## After Starting: Report Status
-
-Tell the user the agent has started and provide monitoring commands.
-
----
-
-## User Available Skills `[USER]`
-
-The following skills are for users (not AI):
-
-| Skill | Description |
-|-------|-------------|
-| `$parallel` | Start Multi-Agent Pipeline (this skill) |
-| `$start` | Start normal development mode (single process) |
-| `$record-session` | Record session progress |
-| `$finish-work` | 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 the 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 worktrees
-- **Don't execute git commit** - the flow handles it in the worktree pipeline
-- **Delegate complex analysis before dispatch** - find specs, inspect code structure, and reduce ambiguity
-- **Prefer focused tasks** - parallelism works best when each worktree has a narrow scope

package/dist/templates/cursor/commands/trellis-before-dev.md

@@ -1,29 +0,0 @@
-Read the relevant development guidelines before starting your task.
-
-Execute these steps:
-
-1. **Discover packages and their spec layers**:
-   ```bash
-   python3 ./.trellis/scripts/get_context.py --mode packages
-   ```
-
-2. **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.)
-
-3. **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.
-
-4. **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.
-
-5. **Always read shared guides**:
-   ```bash
-   cat .trellis/spec/guides/index.md
-   ```
-
-6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
-
-This step is **mandatory** before writing any code.