steerdev 0.4.27__py3-none-any.whl

steerdev_agent/setup/templates/skills/progress-logging/SKILL.md

@@ -0,0 +1,211 @@
+# Progress Logging Skill
+
+This skill provides instructions for writing progress logs during task execution.
+
+**You MUST write progress logs for every task you work on.**
+
+## Why Progress Logging
+
+- **Visibility**: Track what agents are doing in real-time
+- **Debugging**: Understand what happened when things go wrong
+- **Knowledge Transfer**: Document decisions and approaches for future reference
+- **Accountability**: Create an audit trail of work performed
+
+## File Locations
+
+All progress logs are written to the `docs/` directory:
+
+```
+docs/
+├── progress.jsonl                    # Index of all progress events (append-only)
+├── 20260203_143022_add_auth.md       # Detailed progress for a specific task
+├── 20260203_150000_fix_login_bug.md  # Another task's progress
+└── ...
+```
+
+## Progress Markdown Files
+
+Create a detailed markdown file for each task:
+
+**Naming convention**: `docs/{YYYYMMDD_HHMMSS}_{task_name_slug}.md`
+
+**Template**:
+```markdown
+# Task: {Task Title}
+
+**Task ID**: {task-id}
+**Started**: {ISO timestamp}
+**Status**: in-progress | completed | blocked
+
+## Objective
+{Brief description of what needs to be done}
+
+## Progress
+
+### {HH:MM} - {Phase/Action}
+{Description of what was done}
+
+**Files Modified**:
+- `path/to/file.ts` - {what changed}
+
+**Decisions Made**:
+- {Decision and reasoning}
+
+## Blockers
+- {Any blockers encountered}
+
+## Result
+{Final outcome when completed}
+```
+
+## Progress Index (progress.jsonl)
+
+Append a JSON line to `docs/progress.jsonl` for every significant event.
+
+**Format**: One JSON object per line (newline-delimited JSON)
+
+**Required fields**:
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | string | ISO 8601 timestamp |
+| `task_id` | string | Short task ID (first 8 chars of UUID) |
+| `event` | string | Event type (see below) |
+| `message` | string | Human-readable description |
+
+**Optional fields**:
+| Field | Type | Description |
+|-------|------|-------------|
+| `doc_file` | string | Path to detailed progress markdown |
+| `files_modified` | array | List of file paths changed |
+| `pr_url` | string | Pull request URL |
+| `error` | string | Error message (for error events) |
+| `metadata` | object | Additional structured data |
+
+**Event types**:
+| Event | When to Use |
+|-------|-------------|
+| `started` | Beginning work on a task |
+| `progress` | Completing a milestone or significant step |
+| `blocked` | Encountering a blocker |
+| `error` | Encountering an error |
+| `completed` | Finishing the task |
+
+## When to Log
+
+1. **Task Start**: Create progress markdown + log `started` event
+2. **Major Milestones**: Log `progress` for each significant completion
+3. **Every 15-30 minutes**: Log `progress` if still working (keeps session alive)
+4. **Blockers**: Log `blocked` with what's needed to unblock
+5. **Errors**: Log `error` with error details
+6. **Task Completion**: Log `completed` with result and PR URL
+
+## Example Commands
+
+### Start a Task
+```bash
+# Create progress file
+TIMESTAMP=$(date -u +%Y%m%d_%H%M%S)
+TASK_SLUG="add_user_auth"
+DOC_FILE="docs/${TIMESTAMP}_${TASK_SLUG}.md"
+
+cat > "$DOC_FILE" << 'EOF'
+# Task: Add User Authentication
+
+**Task ID**: abc12345
+**Started**: 2026-02-03T14:30:22Z
+**Status**: in-progress
+
+## Objective
+Implement JWT-based authentication with login/logout endpoints.
+
+## Progress
+
+### 14:30 - Starting Implementation
+Beginning work on authentication module.
+EOF
+
+# Log started event
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"started","message":"Beginning auth implementation","doc_file":"'"$DOC_FILE"'"}' >> docs/progress.jsonl
+```
+
+### Log Progress
+```bash
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"progress","message":"JWT token generation complete","files_modified":["src/lib/auth.ts","src/lib/jwt.ts"]}' >> docs/progress.jsonl
+```
+
+### Log Blocker
+```bash
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"blocked","message":"Need database credentials for testing"}' >> docs/progress.jsonl
+```
+
+### Log Error
+```bash
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"error","message":"Build failed","error":"Module not found: @types/node"}' >> docs/progress.jsonl
+```
+
+### Log Completion
+```bash
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"completed","message":"Auth implementation complete with tests","pr_url":"https://github.com/org/repo/pull/42","doc_file":"docs/20260203_143022_add_user_auth.md"}' >> docs/progress.jsonl
+```
+
+## Complete Workflow Example
+
+```bash
+# 1. Get next task
+steerdev tasks next
+# Returns task abc12345: "Add user authentication"
+
+# 2. Mark task as started
+steerdev tasks update abc12345... --status started
+
+# 3. Create progress file and log start
+TIMESTAMP=$(date -u +%Y%m%d_%H%M%S)
+DOC_FILE="docs/${TIMESTAMP}_add_user_auth.md"
+
+cat > "$DOC_FILE" << 'EOF'
+# Task: Add User Authentication
+
+**Task ID**: abc12345
+**Started**: 2026-02-03T14:30:22Z
+**Status**: in-progress
+
+## Objective
+Implement JWT-based authentication.
+
+## Progress
+EOF
+
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"started","message":"Beginning auth implementation","doc_file":"'"$DOC_FILE"'"}' >> docs/progress.jsonl
+
+# 4. Work on the task, logging progress...
+# ... implement features ...
+
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"progress","message":"Login endpoint complete"}' >> docs/progress.jsonl
+
+# 5. Create PR and complete
+git push -u origin HEAD
+gh pr create --title "Add user authentication" --body "..."
+# Returns: https://github.com/org/repo/pull/42
+
+echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task_id":"abc12345","event":"completed","message":"Auth complete","pr_url":"https://github.com/org/repo/pull/42","doc_file":"'"$DOC_FILE"'"}' >> docs/progress.jsonl
+
+# 6. Update task status
+steerdev tasks update abc12345... --status completed --result "Implemented JWT auth. PR: https://github.com/org/repo/pull/42"
+```
+
+## Best Practices
+
+1. **Create the progress file immediately** when starting a task
+2. **Log frequently** - aim for updates every 15-30 minutes of active work
+3. **Be specific** in messages - include what was done, not just "working on it"
+4. **Include file paths** when you modify files
+5. **Document decisions** - explain why you chose an approach
+6. **Update the markdown file** with detailed notes as you work
+7. **Always log completion** with PR URL before marking task done
+
+## Integration with Other Skills
+
+Progress logging works alongside:
+- **Task Management**: Log progress while working on tasks
+- **Activity Reporting**: Progress logs complement API activity reports
+- **Git Workflow**: Include PR URLs in completion logs

steerdev_agent/setup/templates/skills/specs-management/SKILL.md

@@ -0,0 +1,161 @@
+# Specs Management Skill
+
+This skill enables interaction with specification documents (PRDs) via the steerdev.com API.
+
+## Spec Lifecycle
+
+Specs follow a workflow from draft to completion:
+
+```
+DRAFT -> ANALYZING -> CLARIFYING -> PLANNING -> READY -> COMPLETED
+```
+
+| Status | Description |
+|--------|-------------|
+| `draft` | Initial spec, not yet analyzed |
+| `analyzing` | AI is analyzing requirements |
+| `clarifying` | Waiting for clarification |
+| `planning` | Creating implementation plan |
+| `ready` | Ready for task generation |
+| `completed` | Spec has been implemented |
+
+## When to Use
+
+- **Reading requirements**: Fetch spec content to understand what to build
+- **Updating progress**: Update spec status as work progresses
+- **Creating specs**: Document new requirements discovered during work
+- **Listing specs**: Find specs in a project to work on
+
+## Available Commands
+
+### List Specs
+
+```bash
+steerdev specs list [--project-id PROJECT_ID] [--status STATUS] [--limit N] [--compact]
+```
+
+List specification documents with optional filters.
+
+**Options:**
+- `--project-id`, `-p`: Filter by project ID (or use `STEERDEV_PROJECT_ID` env var)
+- `--status`, `-s`: Filter by status (`draft`, `analyzing`, `clarifying`, `planning`, `ready`, `completed`)
+- `--limit`, `-l`: Maximum number of specs to return (default: 20)
+- `--compact`, `-c`: Show truncated IDs instead of full UUIDs
+
+**Example:**
+```bash
+# List all ready specs
+steerdev specs list --status ready
+
+# List specs in a specific project
+steerdev specs list --project-id abc123...
+```
+
+### Get Spec Details
+
+```bash
+steerdev specs get SPEC_ID
+```
+
+Get full details of a specification document including content.
+
+**Arguments:**
+- `SPEC_ID`: Spec ID (UUID) to fetch
+
+**Example:**
+```bash
+steerdev specs get abc123-def456-...
+```
+
+**Returns:**
+- Linear ID (if synced)
+- Title
+- Status
+- Content (markdown)
+- Project ID
+- Source information
+
+### Update Spec
+
+```bash
+steerdev specs update SPEC_ID [OPTIONS]
+```
+
+Update a spec's content, status, or title.
+
+**Options:**
+- `--content`: New content (markdown)
+- `--status`, `-s`: New status
+- `--title`, `-t`: New title
+
+**Example:**
+```bash
+# Update status to ready
+steerdev specs update abc123... --status ready
+
+# Update content
+steerdev specs update abc123... --content "# Updated Requirements
+
+## Overview
+..."
+
+# Update title
+steerdev specs update abc123... --title "New Feature Spec"
+```
+
+### Create Spec
+
+```bash
+steerdev specs create --title "..." --content "..." [OPTIONS]
+```
+
+Create a new specification document.
+
+**Options:**
+- `--title`, `-t`: Spec title (required)
+- `--content`: Spec content in markdown (required)
+- `--project-id`, `-p`: Project ID (or use `STEERDEV_PROJECT_ID` env var)
+- `--source`, `-s`: Source of the spec (default: "agent")
+
+**Example:**
+```bash
+steerdev specs create \
+  --title "User Authentication Feature" \
+  --content "# User Authentication
+
+## Overview
+Implement JWT-based authentication...
+
+## Requirements
+1. Login endpoint
+2. Logout endpoint
+3. Token refresh
+..."
+```
+
+## Workflow Example
+
+```bash
+# List specs ready for implementation
+steerdev specs list --status ready
+
+# Get full spec details
+steerdev specs get abc123...
+
+# After reading, create tasks from the spec
+steerdev tasks create \
+  --title "Implement login endpoint" \
+  --prompt "Based on spec abc123, implement..." \
+  --spec-id abc123...
+
+# Update spec status when all tasks are done
+steerdev specs update abc123... --status completed
+```
+
+## Environment
+
+Requires `STEERDEV_API_KEY` environment variable to be set.
+
+**Optional:**
+- `STEERDEV_API_ENDPOINT`: Override the API base URL (default: https://steerdev.com/api/v1)
+- `STEERDEV_PROJECT_ID`: Default project ID for all commands

steerdev_agent/setup/templates/skills/task-management/SKILL.md

@@ -0,0 +1,343 @@
+# Task Management Skill
+
+This skill enables autonomous task management via steerdev.com API.
+
+**You must respect the task lifecycle.**
+
+## Task Lifecycle
+
+Tasks use Linear-native status_type values:
+
+```
+BACKLOG → UNSTARTED → STARTED → COMPLETED
+```
+
+| Status | Description | Your Action |
+|--------|-------------|-------------|
+| `backlog` | Task is queued, not ready for work | Do not work on these tasks |
+| `unstarted` | Ready to be worked on | Pick up task and move to `started` |
+| `started` | Currently being worked on | Implement the task |
+| `completed` | Task completed | No action needed |
+| `canceled` | Task was canceled | No action needed |
+
+## When to Use
+
+- **At session start**: Fetch the next task to work on
+- **When completing work**: Update task status to `completed` with a result summary
+- **When blocked or need clarification**: Update task with a comment
+- **When discovering new work**: Create sub-tasks
+
+## Available Commands
+
+### Get Next Task
+
+```bash
+steerdev tasks next [--project-id PROJECT_ID]
+```
+
+Returns the highest priority task to work on, automatically prioritizing in this order:
+1. **Started** tasks (to continue work)
+2. **Unstarted** tasks (to start new work)
+3. **Backlog** tasks (if nothing else available)
+
+**Options:**
+- `--project-id`, `-p`: Filter by project ID (or use `STEERDEV_PROJECT_ID` env var)
+
+**Example:**
+```bash
+# Get next task to work on
+steerdev tasks next
+```
+
+### List Tasks
+
+```bash
+steerdev tasks list [--status STATUS] [--project-id PROJECT_ID] [--limit N] [--compact]
+```
+
+List tasks with optional filters.
+
+**Options:**
+- `--status`, `-s`: Filter by status (`backlog`, `unstarted`, `started`, `completed`, `canceled`)
+- `--project-id`, `-p`: Filter by project ID (or use `STEERDEV_PROJECT_ID` env var)
+- `--limit`, `-l`: Maximum number of tasks to return (default: 20)
+- `--compact`, `-c`: Show truncated IDs (8 chars) instead of full UUIDs
+
+### Get Task Details
+
+```bash
+steerdev tasks get TASK_ID
+```
+
+Get details of a specific task by ID.
+
+**Arguments:**
+- `TASK_ID`: Task ID (UUID) to fetch
+
+### Update Task
+
+```bash
+steerdev tasks update TASK_ID [OPTIONS]
+```
+
+Update a task's status or other fields. **Always update to `started` when starting work.**
+
+**Options:**
+- `--status`, `-s`: New status (`backlog`, `unstarted`, `started`, `completed`, `canceled`)
+- `--title`, `-t`: Update task title
+- `--prompt`: Update task prompt
+- `--priority`, `-P`: Update priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)
+- `--result`, `-r`: Result summary (for completed tasks)
+- `--error`, `-e`: Error message (for canceled tasks)
+- `--comment`, `-c`: Comment text (supports markdown)
+
+### Create Task
+
+```bash
+steerdev tasks create --title "..." --prompt "..." [OPTIONS]
+```
+
+Create a new task for discovered work items.
+
+**Options:**
+- `--title`, `-t`: Task title (required)
+- `--prompt`: Task prompt/description (required)
+- `--project-id`, `-p`: Project ID (or use `STEERDEV_PROJECT_ID` env var)
+- `--priority`: Priority 0-4 (default: 3 = medium)
+- `--workdir`, `-w`: Working directory for the task
+- `--spec-id`, `-s`: Specification ID to link this task to
+- `--cycle-id`, `-c`: Cycle ID to link this task to
+
+## Workflow
+
+1. **On start**: Run `steerdev tasks next` to get the next task
+2. **Update task** to `started` before starting work
+3. **Create progress log**: Create `docs/{timestamp}_{task_slug}.md` and log `started` event to `docs/progress.jsonl`
+4. **Create a feature branch**: `git checkout -b task/<task-id-short>`
+5. **Implement** the task (log progress to `docs/progress.jsonl` every 15-30 min)
+6. **Verify visually** (for web/UI changes): Use `agent-browser` to take screenshots and verify changes
+7. **Commit changes** with clear, descriptive commit messages
+8. **Push and create PR**: `git push -u origin HEAD && gh pr create`
+9. **Log completion**: Log `completed` event with PR URL to `docs/progress.jsonl`
+10. **Update task** to `completed` with a result summary and PR URL
+11. **Fetch next task** and repeat
+
+**IMPORTANT**: Always write progress logs. See the Progress Logging skill for details.
+
+## Visual Verification for Web Changes (Required)
+
+**For any task involving web UI changes, you MUST visually verify your work using `agent-browser`.**
+
+### When to Use Browser Verification
+
+- Adding or modifying UI components
+- Changing layouts, styles, or visual elements
+- Implementing new pages or routes
+- Fixing visual bugs
+- Any frontend work in `steerdev-app` or `steerdev.com`
+
+### Development Environment
+
+The `steerdev-app` runs with development settings that **skip Clerk authentication**. You can directly access:
+
+- Dashboard: `http://localhost:3000`
+- All authenticated routes work without login in dev mode
+
+### Verification Workflow
+
+```bash
+# 1. Navigate to the page you modified
+agent-browser open http://localhost:3000/your-page
+
+# 2. Take a snapshot to see interactive elements
+agent-browser snapshot -i
+
+# 3. Take a screenshot to verify visual appearance
+agent-browser screenshot
+
+# 4. For full-page captures
+agent-browser screenshot --full
+
+# 5. If you need to interact (click buttons, fill forms)
+agent-browser click @e1
+agent-browser fill @e2 "test input"
+agent-browser snapshot -i  # Re-snapshot after interactions
+```
+
+### Example: Verifying a New Component
+
+```bash
+# After implementing a new dashboard widget
+agent-browser open http://localhost:3000/dashboard
+agent-browser snapshot -i
+agent-browser screenshot --full
+
+# Check if specific elements rendered correctly
+agent-browser get text @e5  # Get text from specific element
+
+# Test interactions
+agent-browser click @e3     # Click the new button
+agent-browser wait --load networkidle
+agent-browser snapshot -i   # Verify result
+agent-browser screenshot
+```
+
+### Example: Testing Form Changes
+
+```bash
+# Navigate to form page
+agent-browser open http://localhost:3000/settings
+
+# Get initial state
+agent-browser snapshot -i
+agent-browser screenshot
+
+# Fill and submit the form
+agent-browser fill @e1 "Test Value"
+agent-browser select @e2 "Option A"
+agent-browser click @e3  # Submit button
+
+# Verify success state
+agent-browser wait --load networkidle
+agent-browser snapshot -i
+agent-browser screenshot
+```
+
+### Include Screenshots in PR
+
+When creating pull requests for visual changes, mention that screenshots were taken and describe what was verified.
+
+## Git Workflow (Required)
+
+**You MUST use Git and GitHub CLI to manage your work.** Every task implementation must result in a pull request.
+
+### Branch Naming
+
+Create a branch before starting any implementation work:
+
+```bash
+# Use task ID for branch name (use first 8 chars of UUID)
+git checkout -b task/<short-task-id>
+
+# Example
+git checkout -b task/abc12345
+```
+
+### Committing Changes
+
+Make atomic commits with clear, descriptive messages:
+
+```bash
+git add .
+git commit -m "feat: implement user authentication
+
+- Add JWT token generation
+- Create login/logout endpoints
+- Add auth middleware"
+```
+
+Follow conventional commit format:
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `refactor:` - Code refactoring
+- `docs:` - Documentation changes
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks
+
+### Creating Pull Requests
+
+**Always create a PR when completing a task:**
+
+```bash
+# Push branch and create PR
+git push -u origin HEAD
+gh pr create --title "Task: <title>" --body "## Summary
+
+<description of changes>
+
+## Task Reference
+Task ID: <task-id>
+
+## Changes Made
+- Change 1
+- Change 2
+
+## Testing
+- How to test the changes"
+```
+
+### Important Rules
+
+- **Never leave work uncommitted** - Always commit before stopping work
+- **Always create a PR** before marking a task as `completed`
+- **Include PR URL** in the task result summary
+- **Use descriptive commit messages** that explain the "why" not just the "what"
+
+## Example Session
+
+```bash
+# Get next task
+steerdev tasks next
+
+# Mark as started
+steerdev tasks update abc123-... --status started
+
+# Create feature branch
+git checkout -b task/abc12345
+
+# ... implement the task ...
+
+# Commit changes as you work
+git add .
+git commit -m "feat: implement JWT authentication
+
+- Add token generation and validation
+- Create login/logout endpoints
+- Add auth middleware for protected routes"
+
+# Push and create pull request
+git push -u origin HEAD
+gh pr create --title "Add User Authentication" --body "## Summary
+
+Implements JWT-based authentication system.
+
+## Task Reference
+Task ID: abc123-...
+
+## Changes Made
+- JWT token generation in auth service
+- Login/logout endpoints
+- Auth middleware for protected routes
+
+## Testing
+- Run \`npm test\` to execute auth tests
+- Test login flow manually via /api/auth/login"
+
+# Move to completed with PR URL
+steerdev tasks update abc123-... --status completed \
+  --result "Implemented JWT auth with refresh tokens. PR: https://github.com/org/repo/pull/42"
+
+# Get next task
+steerdev tasks next
+```
+
+## Adding Comments
+
+You can add markdown comments to tasks at any time:
+
+```bash
+steerdev tasks update abc123-... --comment "## Progress Update
+
+- Completed initial investigation
+- Found issue in auth module
+- Working on fix"
+```
+
+## Environment
+
+Requires `STEERDEV_API_KEY` environment variable to be set.
+
+**Optional:**
+- `STEERDEV_API_ENDPOINT`: Override the API base URL (default: https://steerdev.com/api/v1)
+- `STEERDEV_PROJECT_ID`: Default project ID for all commands
+- `STEERDEV_AGENT_ID`: Agent ID for tracking