attckdigital/smith/smith-queue

Smith Task Queue

Manage deferred work through a persistent task queue in .smith/vault/queue/. Supports priority ordering, dependency tracking, scheduled execution, status lifecycle management, and batch processing with git worktree isolation.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-queue <event>
 
**User Request:**
> <verbatim user message that triggered this action>
 
**Synthesized Input:** <brief summary>
**Outcome:** <what happened>
**Artifacts:** <files created/modified>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — which subcommand was used
2. After task added/removed/processed/scheduled — task description, queue file path, status change

Queue Entry Format

All queue entries are markdown files in .smith/vault/queue/ with this frontmatter:

---
task: "<task description>"
branch: "<feature branch name — the queue processor checks out this branch via worktree>"
spec_path: "<path to the feature spec folder on the feature branch>"
primary_system: "<system ID, e.g., system-13-trend-intelligence>"
created: "YYYY-MM-DDTHH:MM:SS"
project: "<project directory basename>"
complexity: autonomous|interactive|review
priority: critical|high|medium|low
status: pending|scheduled|in-progress|completed|failed|blocked
depends_on: []
scheduled_for: ""
---
 
## Context
 
<brief description of what this feature does and key decisions>
 
## Artifacts on branch
 
- spec.md — feature specification
- plan.md — implementation plan
- questions.md — clarification questions (all answered)
- <any other artifacts>
 
## Execution Instructions
 
Run `/smith-build` from the `<branch>` branch with feature dir `<spec_path>`.

Required fields: task, branch, spec_path, status, complexity, priority.

Backwards compatibility:

• Entries without priority, depends_on, or scheduled_for → treated as priority: medium, depends_on: [], scheduled_for: ""
• Entries with description instead of task → read description as the task name
• Entries with status: queued → treated as status: pending

Status Lifecycle

pending → scheduled → in-progress → completed
                                   → failed → pending (via requeue)
                    → blocked (if dependency failed)

Every status change MUST append to the ## Status History section in the queue file body:

-`[YYYY-MM-DD HH:MM]` <Status> — <reason or details>

Subcommands

Parse the first word of $ARGUMENTS to determine the subcommand.

add "<description>" [--priority <level>] [--depends-on <filename>]

Creates a new task entry in .smith/vault/queue/.

1. Capture context:

• Task description (from arguments after add, excluding flags)
• Current project directory ($CLAUDE_PROJECT_DIR)
• Current git branch: git rev-parse --abbrev-ref HEAD
• Active feature spec (if on a feature branch, check .specify/systems/)
• Timestamp (UTC)

1. Parse flags:

• --priority <level> — set priority (critical/high/medium/low). Default: medium
• --depends-on <filename> — add dependency on another queue entry. Can be specified multiple times.

1. Determine complexity flag from the description:

• autonomous — task can run without user input (default for clear, specific instructions)
• interactive — task needs user decisions or clarification
• review — run autonomously but stage results for approval
• If unclear, ask the user

1. Generate queue file at .smith/vault/queue/YYYY-MM-DD_HHMMSS-<slug>.md:

```markdown

task: "<task description>" created: "YYYY-MM-DDTHH:MM:SS" project: "<project name>" branch: "<current branch>" spec_path: "<spec path or empty>" complexity: <flag> priority: <level> status: pending depends_on: [<filenames>] scheduled_for: ""

# Task: <description>

## Context

• Project: <project name>
• Branch at creation: <branch>
• Active spec: <spec path or "none">
• Priority: <level>
• Dependencies: <list or "none">

## Instructions

<full task description>

## Notes

<additional context from the conversation>

## Status History

• [YYYY-MM-DD HH:MM] Created — priority: <level>, complexity: <flag>

```

1. Confirm: "Queued: <filename> (priority: <level>, complexity: <flag>)"

list

Show all pending/scheduled queue items sorted by priority then date.

1. Read all .md files in .smith/vault/queue/ (excluding history/ subdirectory and .batch-progress.md)
2. Parse frontmatter for task, created, complexity, priority, status, depends_on
3. Sort: critical → high → medium → low, then oldest first within each level
4. Display:

``` ## Queue — N items

Total: 4 items (2 autonomous, 1 interactive, 1 review) Dependencies: #4 depends on #1

Process a specific task with /smith-queue process <filename>, or run all with /smith-queue process --all. ```

1. If empty: "Queue is empty. Use /smith-queue add \"<description>\" to add a task."

status

Display all queue items grouped by status.

1. Read all files in .smith/vault/queue/ (including history/)
2. Group by status and display:

``` ## Queue Status

### In Progress

• <task> (started <time>)

### Blocked

• <task> — blocked by: <dependency filename> (status: failed)

### Scheduled

• <task> — scheduled for <datetime>

### Pending (by priority)

• 🔴 <task>
• 🟡 <task>

### Recently Completed (last 5)

• <task> — completed <date>

### Recently Failed (last 5)

• <task> — failed <date>: <error summary>

```

process [<filename>] [--all] [--next] [--dry-run] [--limit N] [--priority <level>] [--project <name>] [--all-projects] [--model <model>] [--abort]

The primary command for running queued tasks. Supports interactive selection, specific file processing, and batch execution.

process (no arguments) — Interactive Picker

1. Scan .smith/vault/queue/ for all processable tasks: complexity: autonomous, status: pending or status: queued
2. Sort by priority (critical → high → medium → low), then oldest first
3. Skip items with unmet dependencies
4. Display the list numbered:

``` ## Pending Autonomous Tasks

Which task would you like to process? Enter a number, or "all" to process everything. ```

1. Wait for user to select a number. Then process that single task (see execution steps below).
2. If user says "all", behave as process --all.

process <filename> — Specific Task

Process a specific queue entry by filename. Accepts full filename or partial match.

process --next — Next Highest Priority

Process only the single highest-priority autonomous pending task, then stop. No prompt — just picks the top item and runs it.

process --all — All Pending Tasks

Process all autonomous + pending tasks sequentially in priority order. This is the batch execution mode.

Accepts all batch flags:

• --dry-run — show what would be processed without executing
• --limit <N> — process only the first N items after ordering
• --priority <level> — process only items at or above the given priority (--priority high = critical + high only)
• --project <name> — process queue for a specific project (from ~/.smith/projects.json)
• --all-projects — process across all registered projects, most recently active first
• --model <model> — override model for processing. Default: sonnet. Options: haiku, sonnet, opus
• --abort — if processing is running, create .smith/vault/queue/.abort-batch flag. Current task finishes; remaining return to pending.

Full Pipeline Steps (per task)

These steps apply whether processing a single task or batch. The queue entry is only marked `completed` after the PR is merged. If any step fails, the entry is marked failed with error details and the branch is left intact for manual review.