dot-tasks 0.1.0__tar.gz

dot_tasks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Awni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dot_tasks-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: dot-tasks
+Version: 0.1.0
+Summary: Human-readable and agent-readable task manager with a minimal CLI
+Author: dot-tasks contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Awni00/dot-tasks
+Project-URL: Repository, https://github.com/Awni00/dot-tasks
+Project-URL: Issues, https://github.com/Awni00/dot-tasks/issues
+Keywords: tasks,cli,workflow,productivity,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: InquirerPy>=0.3.4
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/Awni00/dot-tasks/main/assets/logo/svg/banner-dark.svg" media="(prefers-color-scheme: dark)">
+    <source srcset="https://raw.githubusercontent.com/Awni00/dot-tasks/main/assets/logo/svg/banner-light.svg" media="(prefers-color-scheme: light)">
+    <img src="https://raw.githubusercontent.com/Awni00/dot-tasks/main/assets/logo/svg/banner-light.svg" alt="dot-tasks logo">
+  </picture>
+</p>
+
+`dot-tasks` is a small CLI for managing project-level tasks in a local `.tasks/` directory, using human- and agent-readable files.
+
+It started as a personal workflow tool: keep task specs in files, let agents work from those specs, and keep progress updates in the repo instead of chat history. It is shared here in case the same approach is useful to others.
+
+![dot-tasks CLI demo](assets/demo/cli-demo.gif)
+
+<p align="center">
+  <a href="https://github.com/Awni00/dot-tasks/actions/workflows/tests.yml"><img src="https://github.com/Awni00/dot-tasks/actions/workflows/tests.yml/badge.svg" alt="Unit Tests"></a>
+  <a href="https://github.com/Awni00/dot-tasks/actions/workflows/publish.yml"><img src="https://github.com/Awni00/dot-tasks/actions/workflows/publish.yml/badge.svg" alt="Publish"></a>
+  <a href="https://pypi.org/project/dot-tasks/"><img src="https://img.shields.io/pypi/v/dot-tasks" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+</p>
+
+## High-level Workflow
+
+This is the workflow I usually follow.
+
+| Step | What happens | Command(s) | Files touched |
+| --- | --- | --- | --- |
+| Make note of new to-do | Write down the task spec. Often I have an agent draft a spec from a rough note. | `dot-tasks create` | Creates task dir `.tasks/todo/<created-date>-<task_name>/` with `task.md`, `activity.md`|
+| Choose task to work on | Scan what is in `todo`/`doing` and pick the next task to start. | `dot-tasks list` | read-only inspection of `.tasks/` |
+| Start active work | Move the task to active status when implementation begins. | `dot-tasks start` | Move task from `.tasks/todo/` to `.tasks/doing/`; `plan.md` created |
+| Work loop | Log notable progress updates so humans and agents share context. | `dot-tasks update` | `task.md`, `activity.md` |
+| Finish and archive state | Mark done when acceptance criteria are met, preserving full history in files. | `dot-tasks complete` | task directory moves to `.tasks/done/`|
+
+## Contents
+
+- [High-level Workflow](#high-level-workflow)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Task Layout](#task-layout)
+- [Commands](#commands)
+- [AI Agent Integration](#ai-agent-integration)
+- [Example Project](#example-project)
+
+## Installation
+
+### Install via pip (PyPI)
+
+```bash
+pip install dot-tasks
+```
+
+Quick check:
+
+```bash
+dot-tasks --help
+```
+
+### Install Latest from GitHub
+
+Install the latest from GitHub:
+
+```bash
+pip install "git+https://github.com/Awni00/dot-tasks.git"
+```
+
+### Development Install (with uv)
+
+```bash
+git clone https://github.com/Awni00/dot-tasks.git
+cd dot-tasks
+uv sync --dev
+uv run dot-tasks --help
+```
+
+Editable install:
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+dot-tasks init
+dot-tasks create add-task-manager --summary "Build initial package"
+dot-tasks start add-task-manager
+dot-tasks update add-task-manager --note "Implemented storage layer"
+dot-tasks complete add-task-manager
+```
+
+## Task Layout
+
+```text
+.tasks/
+  todo/
+  doing/
+  done/
+  trash/
+```
+
+Each task lives in `.tasks/<status-bucket>/<created-date>-<task_name>/` and contains:
+
+- `task.md` (canonical metadata frontmatter + task body)
+- `activity.md` (append-only audit log)
+- `plan.md` (created when the task is started)
+
+## Commands
+
+| Command | Purpose | Typical usage |
+| --- | --- | --- |
+| `init` | Create `.tasks/` and write/update managed config settings; can also append workflow guidance section AGENTS.md and install the skill via `npx skills`. | `dot-tasks init` |
+| `create` | Add a new task to `todo/`. | `dot-tasks create <task_name>` |
+| `start` | Move a task to `doing/` and create `plan.md`. | `dot-tasks start <task_name>` |
+| `complete` | Move a task to `done/`. | `dot-tasks complete <task_name>` |
+| `list` | List tasks by status (rich/plain/JSON depending on context). | `dot-tasks list [todo|doing|done] [--json]` |
+| `view` | Show full details for one task. | `dot-tasks view <task_name> [--json]` |
+| `update` | Update metadata, dependencies, tags, or add notes. | `dot-tasks update <task_name> ...` |
+| `rename` | Rename a task. | `dot-tasks rename <task_name> <new_task_name>` |
+| `delete` | Move a task to `trash/`, or delete permanently with `--hard`. | `dot-tasks delete <task_name> [--hard]` |
+
+## AI Agent Integration
+
+`dot-tasks` is designed so humans and agents can work from the same file-based task state in `.tasks/` instead of relying on chat context.
+
+Typical agent workflow:
+
+1. Capture or refine a task spec with `dot-tasks create`.
+2. If asked what to work on, check `dot-tasks list` (`todo`/`doing`) and propose the top few options with a short rationale.
+3. Move selected work into active state with `dot-tasks start`.
+4. Log meaningful progress with `dot-tasks update --note ...` as work evolves.
+5. Close the loop with `dot-tasks complete` when acceptance criteria are met.
+
+`dot-tasks init` can also set up integration pieces:
+
+- It can append a canonical **“Task management with `dot-tasks`”** section to your project `AGENTS.md`.
+- It can run:
+  `npx skills add Awni00/dot-tasks --skill dot-tasks`
+  to install the `dot-tasks` skill.
+
+## Example Project
+
+For a full demo of the workflow, see [`examples/basic-demo/`](examples/basic-demo/) and the walkthrough in [`examples/basic-demo/README.md`](examples/basic-demo/README.md).

dot_tasks-0.1.0/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/Awni00/dot-tasks/main/assets/logo/svg/banner-dark.svg" media="(prefers-color-scheme: dark)">
+    <source srcset="https://raw.githubusercontent.com/Awni00/dot-tasks/main/assets/logo/svg/banner-light.svg" media="(prefers-color-scheme: light)">
+    <img src="https://raw.githubusercontent.com/Awni00/dot-tasks/main/assets/logo/svg/banner-light.svg" alt="dot-tasks logo">
+  </picture>
+</p>
+
+`dot-tasks` is a small CLI for managing project-level tasks in a local `.tasks/` directory, using human- and agent-readable files.
+
+It started as a personal workflow tool: keep task specs in files, let agents work from those specs, and keep progress updates in the repo instead of chat history. It is shared here in case the same approach is useful to others.
+
+![dot-tasks CLI demo](assets/demo/cli-demo.gif)
+
+<p align="center">
+  <a href="https://github.com/Awni00/dot-tasks/actions/workflows/tests.yml"><img src="https://github.com/Awni00/dot-tasks/actions/workflows/tests.yml/badge.svg" alt="Unit Tests"></a>
+  <a href="https://github.com/Awni00/dot-tasks/actions/workflows/publish.yml"><img src="https://github.com/Awni00/dot-tasks/actions/workflows/publish.yml/badge.svg" alt="Publish"></a>
+  <a href="https://pypi.org/project/dot-tasks/"><img src="https://img.shields.io/pypi/v/dot-tasks" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+</p>
+
+## High-level Workflow
+
+This is the workflow I usually follow.
+
+| Step | What happens | Command(s) | Files touched |
+| --- | --- | --- | --- |
+| Make note of new to-do | Write down the task spec. Often I have an agent draft a spec from a rough note. | `dot-tasks create` | Creates task dir `.tasks/todo/<created-date>-<task_name>/` with `task.md`, `activity.md`|
+| Choose task to work on | Scan what is in `todo`/`doing` and pick the next task to start. | `dot-tasks list` | read-only inspection of `.tasks/` |
+| Start active work | Move the task to active status when implementation begins. | `dot-tasks start` | Move task from `.tasks/todo/` to `.tasks/doing/`; `plan.md` created |
+| Work loop | Log notable progress updates so humans and agents share context. | `dot-tasks update` | `task.md`, `activity.md` |
+| Finish and archive state | Mark done when acceptance criteria are met, preserving full history in files. | `dot-tasks complete` | task directory moves to `.tasks/done/`|
+
+## Contents
+
+- [High-level Workflow](#high-level-workflow)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Task Layout](#task-layout)
+- [Commands](#commands)
+- [AI Agent Integration](#ai-agent-integration)
+- [Example Project](#example-project)
+
+## Installation
+
+### Install via pip (PyPI)
+
+```bash
+pip install dot-tasks
+```
+
+Quick check:
+
+```bash
+dot-tasks --help
+```
+
+### Install Latest from GitHub
+
+Install the latest from GitHub:
+
+```bash
+pip install "git+https://github.com/Awni00/dot-tasks.git"
+```
+
+### Development Install (with uv)
+
+```bash
+git clone https://github.com/Awni00/dot-tasks.git
+cd dot-tasks
+uv sync --dev
+uv run dot-tasks --help
+```
+
+Editable install:
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+dot-tasks init
+dot-tasks create add-task-manager --summary "Build initial package"
+dot-tasks start add-task-manager
+dot-tasks update add-task-manager --note "Implemented storage layer"
+dot-tasks complete add-task-manager
+```
+
+## Task Layout
+
+```text
+.tasks/
+  todo/
+  doing/
+  done/
+  trash/
+```
+
+Each task lives in `.tasks/<status-bucket>/<created-date>-<task_name>/` and contains:
+
+- `task.md` (canonical metadata frontmatter + task body)
+- `activity.md` (append-only audit log)
+- `plan.md` (created when the task is started)
+
+## Commands
+
+| Command | Purpose | Typical usage |
+| --- | --- | --- |
+| `init` | Create `.tasks/` and write/update managed config settings; can also append workflow guidance section AGENTS.md and install the skill via `npx skills`. | `dot-tasks init` |
+| `create` | Add a new task to `todo/`. | `dot-tasks create <task_name>` |
+| `start` | Move a task to `doing/` and create `plan.md`. | `dot-tasks start <task_name>` |
+| `complete` | Move a task to `done/`. | `dot-tasks complete <task_name>` |
+| `list` | List tasks by status (rich/plain/JSON depending on context). | `dot-tasks list [todo|doing|done] [--json]` |
+| `view` | Show full details for one task. | `dot-tasks view <task_name> [--json]` |
+| `update` | Update metadata, dependencies, tags, or add notes. | `dot-tasks update <task_name> ...` |
+| `rename` | Rename a task. | `dot-tasks rename <task_name> <new_task_name>` |
+| `delete` | Move a task to `trash/`, or delete permanently with `--hard`. | `dot-tasks delete <task_name> [--hard]` |
+
+## AI Agent Integration
+
+`dot-tasks` is designed so humans and agents can work from the same file-based task state in `.tasks/` instead of relying on chat context.
+
+Typical agent workflow:
+
+1. Capture or refine a task spec with `dot-tasks create`.
+2. If asked what to work on, check `dot-tasks list` (`todo`/`doing`) and propose the top few options with a short rationale.
+3. Move selected work into active state with `dot-tasks start`.
+4. Log meaningful progress with `dot-tasks update --note ...` as work evolves.
+5. Close the loop with `dot-tasks complete` when acceptance criteria are met.
+
+`dot-tasks init` can also set up integration pieces:
+
+- It can append a canonical **“Task management with `dot-tasks`”** section to your project `AGENTS.md`.
+- It can run:
+  `npx skills add Awni00/dot-tasks --skill dot-tasks`
+  to install the `dot-tasks` skill.
+
+## Example Project
+
+For a full demo of the workflow, see [`examples/basic-demo/`](examples/basic-demo/) and the walkthrough in [`examples/basic-demo/README.md`](examples/basic-demo/README.md).

dot_tasks-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dot-tasks"
+dynamic = ["version"]
+description = "Human-readable and agent-readable task manager with a minimal CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "dot-tasks contributors"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Utilities",
+]
+keywords = ["tasks", "cli", "workflow", "productivity", "automation"]
+dependencies = [
+  "typer>=0.12",
+  "PyYAML>=6.0",
+  "InquirerPy>=0.3.4",
+  "rich>=13.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Awni00/dot-tasks"
+Repository = "https://github.com/Awni00/dot-tasks"
+Issues = "https://github.com/Awni00/dot-tasks/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+dot-tasks = "dot_tasks.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dot_tasks = ["resources/agents/*.md"]
+
+[tool.setuptools.dynamic]
+version = {attr = "dot_tasks._version.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dot_tasks-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dot_tasks-0.1.0/src/dot_tasks/__init__.py

@@ -0,0 +1,5 @@
+"""dot-tasks package."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

dot_tasks-0.1.0/src/dot_tasks/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

dot_tasks-0.1.0/src/dot_tasks/_version.py

@@ -0,0 +1,3 @@
+"""Version definition for dot-tasks."""
+
+__version__ = "0.1.0"

dot_tasks-0.1.0/src/dot_tasks/agents_snippet.py

@@ -0,0 +1,80 @@
+"""Helpers for loading and upserting AGENTS.md snippets."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import Literal
+
+
+BEGIN_MARKER = "<!-- dot-tasks:begin task-management -->"
+END_MARKER = "<!-- dot-tasks:end task-management -->"
+RESOURCE_PATH = "resources/agents/task-management-dot-tasks.md"
+
+
+def _normalize_newlines(text: str) -> str:
+    return text.replace("\r\n", "\n")
+
+
+def _validate_markers(text: str) -> None:
+    begin = text.find(BEGIN_MARKER)
+    end = text.find(END_MARKER)
+    if begin == -1 or end == -1 or begin > end:
+        raise ValueError("Invalid task-management snippet: missing or misordered markers.")
+
+
+def load_task_management_snippet() -> str:
+    """Load canonical markdown section for AGENTS integration."""
+    content = resources.files("dot_tasks").joinpath(RESOURCE_PATH).read_text(encoding="utf-8")
+    normalized = _normalize_newlines(content).strip("\n")
+    _validate_markers(normalized)
+    return normalized + "\n"
+
+
+def resolve_agents_file(project_root: Path, agents_file: Path | None) -> Path:
+    target = Path("AGENTS.md") if agents_file is None else agents_file
+    if target.is_absolute():
+        return target
+    return (project_root / target).resolve()
+
+
+def upsert_task_management_snippet(
+    target_file: Path,
+    snippet_text: str,
+) -> Literal["created", "updated", "appended", "unchanged"]:
+    """Insert or replace canonical task-management snippet in target markdown file."""
+    block = _normalize_newlines(snippet_text).strip("\n")
+    _validate_markers(block)
+    block = block + "\n"
+
+    target_file.parent.mkdir(parents=True, exist_ok=True)
+    if not target_file.exists():
+        target_file.write_text(block, encoding="utf-8")
+        return "created"
+
+    existing = _normalize_newlines(target_file.read_text(encoding="utf-8"))
+    begin = existing.find(BEGIN_MARKER)
+    end = existing.find(END_MARKER)
+
+    if begin != -1 and end != -1 and begin < end:
+        end_with_marker = end + len(END_MARKER)
+        replacement = existing[:begin] + block.rstrip("\n") + existing[end_with_marker:]
+        if not replacement.endswith("\n"):
+            replacement = replacement + "\n"
+        if replacement == existing:
+            return "unchanged"
+        target_file.write_text(replacement, encoding="utf-8")
+        return "updated"
+
+    if block.rstrip("\n") in existing:
+        return "unchanged"
+
+    separator = ""
+    if existing and not existing.endswith("\n"):
+        separator = "\n"
+    if existing.rstrip("\n"):
+        separator = separator + "\n"
+
+    appended = existing + separator + block
+    target_file.write_text(appended, encoding="utf-8")
+    return "appended"