deepspider 0.1.0

package/.claude/commands/trellis/parallel.md

@@ -0,0 +1,193 @@
+# 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
+./.trellis/scripts/get-context.sh
+```
+
+### Step 3: Read Project Guidelines `[AI]`
+
+```bash
+cat .trellis/spec/frontend/index.md  # Frontend guidelines index
+cat .trellis/spec/backend/index.md   # Backend guidelines index
+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
+./.trellis/scripts/multi-agent/plan.sh \
+  --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.sh completes, start the worktree agent:
+
+```bash
+./.trellis/scripts/multi-agent/trellis:start.sh "$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=$(./.trellis/scripts/task.sh create "<title>" --slug <task-name>)
+```
+
+#### Step 2: Configure Task
+
+```bash
+# Initialize jsonl context files
+./.trellis/scripts/task.sh init-context "$TASK_DIR" <dev_type>
+
+# Set branch and scope
+./.trellis/scripts/task.sh set-branch "$TASK_DIR" feature/<name>
+./.trellis/scripts/task.sh set-scope "$TASK_DIR" <scope>
+```
+
+#### Step 3: Add Context (optional: use research agent)
+
+```bash
+./.trellis/scripts/task.sh add-context "$TASK_DIR" implement "<path>" "<reason>"
+./.trellis/scripts/task.sh add-context "$TASK_DIR" check "<path>" "<reason>"
+```
+
+#### Step 4: Create prd.md
+
+```bash
+cat > "$TASK_DIR/prd.md" << 'EOF'
+# Feature: <name>
+
+## Requirements
+- ...
+
+## Acceptance Criteria
+- ...
+EOF
+```
+
+#### Step 5: Validate and Start
+
+```bash
+./.trellis/scripts/task.sh validate "$TASK_DIR"
+./.trellis/scripts/multi-agent/trellis:start.sh "$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 |
+|---------|-------------|
+| `/trellis:parallel` | Start Multi-Agent Pipeline (this command) |
+| `/trellis:start` | Start normal development mode (single process) |
+| `/trellis:record-session` | Record session progress |
+| `/trellis:finish-work` | Pre-completion checklist |
+
+---
+
+## Monitoring Commands (for user reference)
+
+Tell the user they can use these commands to monitor:
+
+```bash
+./.trellis/scripts/multi-agent/status.sh                    # Overview
+./.trellis/scripts/multi-agent/status.sh --log <name>       # View log
+./.trellis/scripts/multi-agent/status.sh --watch <name>     # Real-time monitoring
+./.trellis/scripts/multi-agent/cleanup.sh <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/.claude/commands/trellis/record-session.md

@@ -0,0 +1,62 @@
+[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
+
+**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+
+---
+
+## Record Work Progress (Simplified - Only 2 Steps)
+
+### Step 1: Get Context
+
+```bash
+./.trellis/scripts/get-context.sh
+```
+
+### Step 2: One-Click Add Session
+
+```bash
+# Method 1: Simple parameters
+./.trellis/scripts/add-session.sh \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what was done"
+
+# Method 2: Pass detailed content via stdin
+cat << 'EOF' | ./.trellis/scripts/add-session.sh --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] Updates index.md (Total Sessions +1, Last Active, line stats, history)
+
+---
+
+## Archive Completed Task (if any)
+
+If a task was completed this session:
+
+```bash
+./.trellis/scripts/task.sh archive <task-name>
+```
+
+---
+
+## Script Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `get-context.sh` | Get all context info |
+| `add-session.sh --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `task.sh create "<title>" [--slug <name>]` | Create new task directory |
+| `task.sh archive <name>` | Archive completed task |
+| `task.sh list` | List active tasks |

package/.claude/commands/trellis/start.md

@@ -0,0 +1,280 @@
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+---
+
+## Operation Types
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
+| `[USER]` | Slash commands executed by user | User |
+
+---
+
+## Initialization `[AI]`
+
+### Step 1: Understand Development Workflow
+
+First, read the workflow guide to understand the development process:
+
+```bash
+cat .trellis/workflow.md
+```
+
+**Follow the instructions in workflow.md** - it contains:
+- Core principles (Read Before Write, Follow Standards, etc.)
+- File system structure
+- Development process
+- Best practices
+
+### Step 2: Get Current Context
+
+```bash
+./.trellis/scripts/get-context.sh
+```
+
+This shows: developer identity, git status, current task (if any), active tasks.
+
+### Step 3: Read Guidelines Index
+
+```bash
+cat .trellis/spec/frontend/index.md  # Frontend guidelines
+cat .trellis/spec/backend/index.md   # Backend guidelines
+cat .trellis/spec/guides/index.md    # Thinking guides
+```
+
+### Step 4: Report and Ask
+
+Report what you learned and ask: "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 |
+| **Development Task** | Any code change that: modifies logic, adds features, fixes bugs, touches multiple files | **Task Workflow** |
+
+### Decision Rule
+
+> **If in doubt, use Task Workflow.**
+>
+> Task Workflow ensures specs are injected to agents, resulting in higher quality code.
+> The overhead is minimal, but the benefit is significant.
+
+---
+
+## 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`
+
+---
+
+## Task Workflow (Development Tasks)
+
+**Why this workflow?**
+- Research Agent analyzes what specs are needed
+- Specs are configured in jsonl files
+- Implement Agent receives specs via Hook injection
+- Check Agent verifies against specs
+- Result: Code that follows project conventions automatically
+
+### Step 1: Understand the Task `[AI]`
+
+Before creating anything, understand what user wants:
+- What is the goal?
+- What type of development? (frontend / backend / fullstack)
+- Any specific requirements or constraints?
+
+If unclear, ask clarifying questions.
+
+### Step 2: Research the Codebase `[AI]`
+
+Call Research Agent to analyze:
+
+```
+Task(
+  subagent_type: "research",
+  prompt: "Analyze the codebase for this task:
+
+  Task: <user's task description>
+  Type: <frontend/backend/fullstack>
+
+  Please find:
+  1. Relevant spec files in .trellis/spec/
+  2. Existing code patterns to follow (find 2-3 examples)
+  3. Files that will likely need modification
+
+  Output:
+  ## Relevant Specs
+  - <path>: <why it's relevant>
+
+  ## Code Patterns Found
+  - <pattern>: <example file path>
+
+  ## Files to Modify
+  - <path>: <what change>
+
+  ## Suggested Task Name
+  - <short-slug-name>",
+  model: "opus"
+)
+```
+
+### Step 3: Create Task Directory `[AI]`
+
+Based on research results:
+
+```bash
+TASK_DIR=$(./.trellis/scripts/task.sh create "<title from research>" --slug <suggested-slug>)
+```
+
+### Step 4: Configure Context `[AI]`
+
+Initialize default context:
+
+```bash
+./.trellis/scripts/task.sh init-context "$TASK_DIR" <type>
+# type: backend | frontend | fullstack
+```
+
+Add specs found by Research Agent:
+
+```bash
+# For each relevant spec and code pattern:
+./.trellis/scripts/task.sh add-context "$TASK_DIR" implement "<path>" "<reason>"
+./.trellis/scripts/task.sh add-context "$TASK_DIR" check "<path>" "<reason>"
+```
+
+### Step 5: Write Requirements `[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>
+```
+
+### Step 6: Activate Task `[AI]`
+
+```bash
+./.trellis/scripts/task.sh start "$TASK_DIR"
+```
+
+This sets `.current-task` so hooks can inject context.
+
+### Step 7: Implement `[AI]`
+
+Call Implement Agent (specs are auto-injected by hook):
+
+```
+Task(
+  subagent_type: "implement",
+  prompt: "Implement the task described in prd.md.
+
+  Follow all specs that have been injected into your context.
+  Run lint and typecheck before finishing.",
+  model: "opus"
+)
+```
+
+### Step 8: Check Quality `[AI]`
+
+Call Check Agent (specs are auto-injected by hook):
+
+```
+Task(
+  subagent_type: "check",
+  prompt: "Review all code changes against the specs.
+
+  Fix any issues you find directly.
+  Ensure lint and typecheck pass.",
+  model: "opus"
+)
+```
+
+### Step 9: 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
+
+---
+
+## Continuing Existing Task
+
+If `get-context.sh` shows a current task:
+
+1. Read the task's `prd.md` to understand the goal
+2. Check `task.json` for current status and phase
+3. Ask user: "Continue working on <task-name>?"
+
+If yes, resume from the appropriate step (usually Step 7 or 8).
+
+---
+
+## Commands Reference
+
+### User Commands `[USER]`
+
+| Command | When to Use |
+|---------|-------------|
+| `/trellis:start` | Begin a session (this command) |
+| `/trellis:parallel` | Complex tasks needing isolated worktree |
+| `/trellis:finish-work` | Before committing changes |
+| `/trellis:record-session` | After completing a task |
+
+### AI Scripts `[AI]`
+
+| Script | Purpose |
+|--------|---------|
+| `get-context.sh` | Get session context |
+| `task.sh create` | Create task directory |
+| `task.sh init-context` | Initialize jsonl files |
+| `task.sh add-context` | Add spec to jsonl |
+| `task.sh start` | Set current task |
+| `task.sh finish` | Clear current task |
+| `task.sh archive` | Archive completed task |
+
+### Sub Agents `[AI]`
+
+| Agent | Purpose | Hook Injection |
+|-------|---------|----------------|
+| research | Analyze codebase | No (reads directly) |
+| implement | Write code | Yes (implement.jsonl) |
+| check | Review & fix | Yes (check.jsonl) |
+| debug | Fix specific issues | Yes (debug.jsonl) |
+
+---
+
+## Key Principle
+
+> **Specs are injected, not remembered.**
+>
+> The Task Workflow ensures agents receive relevant specs automatically.
+> This is more reliable than hoping the AI "remembers" conventions.