DOCSEARCHbyAlgolia
Submit Docs

TaskSync Documentation

repository·main·Indexed 20 days ago

https://github.com/4regab/tasksync

A suite of tools and a VS Code extension for managing human-in-the-loop workflows in AI-assisted development. TaskSync allows users to batch and queue prompts, utilize an autonomous 'Autopilot' mode, and manage tasks via a terminal-based agent protocol or an MCP Server. It includes features for remote access via LAN or Tailscale, context referencing with # mentions, and specific tool instructions to maintain interaction cycles using the ask_user tool.

Tokens
18.1K
Snippets
45
Records
84
Agent score
71%

What's inside TaskSync

  1. What is TaskSync?

    main
    TaskSync is a VS Code extension designed for a 'human-in-the-loop' workflow. It allows you to batch and queue prompts to AI agents, enabling them to perform long-running or repetitive tasks while you remain focused or away from your desk. It supports multiple modes of interaction, including automated queuing and autonomous 'Autopilot' modes.

  2. Understand the TaskSync V5 Protocol behavior

    main

    The TaskSync V5 Protocol defines an autonomous agent behavior model where the agent operates in a continuous, indefinite task cycle. The agent is designed to never end a session or use polite concluding phrases (like "How can I help you?") in the chat interface. Instead, all task requests and questions must be routed through specific terminal commands to maintain an active, non-terminating loop.

    Core Mental Model:

    • Continuous Loop: Complete Task $\rightarrow$ Request next task via terminal $\rightarrow$ Process $\rightarrow$ Repeat.
    • Terminal-First Communication: The agent uses the run_in_terminal tool to prompt the user for input, rather than relying on the standard chat interface for task acquisition.
    • No Concluding Phrases: The agent is strictly forbidden from using phrases that suggest a conversation is ending (e.g., "Let me know if you need anything else").

  3. The Spec Creation Workflow Overview

    main

    The Spec Creation Workflow is a systematic, iterative process designed to transform a rough feature idea into a detailed design document and an actionable implementation plan. It follows a spec-driven development methodology consisting of three main phases: Requirement Gathering, Feature Design, and Task List Creation.

    Key principles include:

    • Iterative Refinement: Moving between requirements, research, and design as needed.
    • Ground-Truth Establishment: Ensuring the user explicitly approves each document before proceeding to the next phase.
    • Artifact-Centric: All progress is captured in specific Markdown files within a .tasksync/specs/{feature_name}/ directory.
    • Separation of Concerns: This workflow is strictly for creating design and planning artifacts; actual code implementation is handled in a separate workflow.

  4. How the TaskSync V5 Protocol operational states work

    main

    The TaskSync V5 Protocol operates through three distinct states to ensure continuous, focused task execution without automatic session termination:

    1. State 1: Active Task Execution: The agent focuses entirely on the assigned task, monitoring for completion milestones. It only transitions to State 2 once the task is fully completed according to specifications.
    2. State 2: Task Request Mode: Triggered immediately after task completion. The agent must never use concluding statements (e.g., "task complete") or goodbye phrases. Instead, it must announce "Task completed. Requesting next task from terminal." and immediately execute the universal task request command to wait for user input.
    3. State 3: Manual Termination Only: The agent is prohibited from terminating the session automatically. The session only ends when the user provides an explicit termination command such as stop, end, terminate, or quit via the terminal.

    If no task is provided during State 2 (e.g., the user inputs none), the agent enters a standby mode, performing periodic task requests every 60 seconds.

    State 1: Active Task Execution
State 2: Task Request Mode (Mandatory Task Request Announcement + Universal Command)
State 3: Manual Termination Only

  5. Understand the TaskSync V5 Operational States

    main

    TaskSync operates using a strict state machine to ensure continuous task execution and prevent accidental session termination. Understanding these states is critical for managing the agent's lifecycle:

    1. State 1: Active Task Execution: The agent is focused on a single assigned task. It will work continuously until the task meets completion criteria or an urgent override is received.
    2. State 2: Task Request Mode: Triggered immediately upon task completion. In this state, the agent must not use concluding phrases (e.g., "Let me know if you need help"). Instead, it must announce it is requesting a new task and immediately execute the universal terminal command to wait for input. This state is intended to loop indefinitely.
    3. State 3: Manual Termination Only: The agent is prohibited from self-terminating. The session only ends when the user provides an explicit termination command such as stop, end, terminate, or quit via the terminal.

  6. Use the Terminal Task Input System

    main

    TaskSync relies on OS-specific shell commands to receive instructions via the terminal. This ensures a continuous loop of task execution without relying on standard chat interfaces for control flow.

    Task Request Commands:

    • Windows (PowerShell): Use Read-Host to prompt for input.
    • macOS/Linux (bash/zsh): Use read -p to prompt for input.

    Special Commands:

    • none: Puts the agent in standby mode (it will periodically request tasks every 60 seconds).
    • stop, quit, end, terminate: Triggers the manual termination protocol.
    # macOS/Linux
read -p "Enter your task: " task

# Windows
$task = Read-Host "Enter your task"

  7. Understand the TaskSync V4 Operational States

    main

    TaskSync operates using a strict three-state lifecycle to ensure continuous task execution and prevent premature session termination.

    1. State 1: Active Task Execution: The agent focuses exclusively on the assigned task. It monitors for completion milestones and will not transition to State 2 until the task is fully completed according to specifications.
    2. State 2: Task Request Mode: Triggered immediately upon task completion. The agent enters a continuous loop where it announces task completion and uses terminal commands to request the next task. This state is designed to be indefinite; the agent must never use concluding phrases or wait for a prompt before requesting the next task.
    3. State 3: Manual Termination Only: The agent is prohibited from automatic termination. The session only ends when the user provides an explicit termination command such as stop, end, terminate, or quit via the terminal.

  8. TaskSync V4 Protocol: Core Operational Model

    main

    The TaskSync V4 Protocol defines an autonomous agent behavior model where the agent operates in a continuous, indefinite task cycle. The agent is strictly forbidden from ending a session, using concluding phrases (e.g., "Let me know if you need anything else"), or waiting for user input in the chat interface. Instead, the agent must use terminal commands to request new tasks and ask questions, ensuring the conversation remains active through the terminal interface.

    Key Operational Rules:

    • Continuous Cycle: Complete task $\rightarrow$ Request next task via terminal $\rightarrow$ Process $\rightarrow$ Repeat.
    • Terminal-First Input: All task requests and questions must be executed via the run_in_terminal tool using OS-specific commands.
    • Manual Termination Only: The session only ends when the user provides explicit termination commands such as stop, end, terminate, or quit via the terminal.

  9. Understand the TaskSync Spec Creation Workflow

    main

    The TaskSync workflow follows a strict sequential lifecycle for creating and executing features. The process moves through three primary phases, each requiring explicit user approval before proceeding to the next.

    The Three Phases

    1. Requirements: Writing the requirements.md document.
    2. Design: Writing the design.md document.
    3. Tasks: Writing the tasks.md document (the implementation plan).

    Workflow Lifecycle

    • Sequential Order: You cannot skip ahead (e.g., you cannot write a Design before Requirements are approved).
    • Feedback Loops: Each phase includes a Review state. If you provide feedback, the model revises the document and must ask for approval again.
    • Explicit Approval: The model requires a clear "yes", "approved", or equivalent affirmative response to move from Review to the next phase.
    • Entry Points: Users can enter the workflow at any stage to Update an existing document or to Execute a task from an existing spec.

    Completion

    Once the tasks.md document is approved, the workflow is considered complete, and the model will ask permission to begin executing the tasks.

  10. How TaskSync modes work: Smart Queue, Normal, and Autopilot

    main

    TaskSync offers three primary interaction modes:

    • Normal Mode: Direct, manual interaction where you respond to each AI request as it arrives.
    • Smart Queue Mode: You can queue multiple prompts in advance. These prompts are automatically sent only when the AI agent requests feedback (via ask_user). This is ideal for pre-loading instructions for predictable workflows.
    • Autopilot: Enables autonomous operation by automatically responding to ask_user prompts.
      • Prompts cycle in order (1→2→3→1...) with each call.
      • Queue Priority: Queued prompts are always sent first; Autopilot only triggers when the queue is empty.
      • You can toggle Autopilot on/off via the switch below the send button or in Settings.

  11. Understand the TaskSync V5 Protocol operational model

    main

    The TaskSync V5 Protocol defines an autonomous agent behavior model designed for continuous, indefinite task execution. The core mental model is a Continuous Task Cycle:

    1. Initialization: The agent announces initialization and immediately requests a task via the terminal.
    2. Task Execution: The agent processes the task with full focus.
    3. Immediate Request: Upon task completion, the agent must immediately request the next task via the terminal without waiting for user permission or using polite concluding phrases.
    4. Repeat: The cycle continues indefinitely.

    Key Constraints:

    • No Automatic Termination: The session must never end unless the user provides an explicit termination command (stop, end, terminate, or quit).
    • No Concluding Phrases: The agent is strictly forbidden from using phrases like "Let me know if you need anything else" or "How can I help?".
    • Terminal-First Communication: All task inputs and questions must be routed through the terminal using specific Python commands via the run_in_terminal tool.

  12. Understand the TaskSync V5 Protocol

    main

    The TaskSync V5 Protocol defines an autonomous agent behavior model designed for continuous, indefinite task execution. The agent operates as a loop: it executes a task, announces completion, and immediately requests a new task via a terminal command.

    Core Mental Model:

    • Continuous Operation: The agent must never end a session or use concluding phrases (e.g., "Let me know if you need anything else").
    • Terminal-Centric Input: All task requests and questions must be facilitated through specific Python terminal commands using the run_in_terminal tool, rather than standard chat interaction.
    • Manual Termination Only: The session only ends when the user provides explicit termination commands such as stop, end, terminate, or quit via the terminal.