taskill/PKG-INFO at main · semcod/taskill · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
Metadata-Version: 2.4
Name: taskill
Version: 0.1.0
Summary: Daily project hygiene: keep README / CHANGELOG / TODO in sync with reality. LLM-first, algorithmic fallback.
Project-URL: Homepage, https://github.com/oqlos/taskill
Project-URL: Issues, https://github.com/oqlos/taskill/issues
Author: Tom Sapletta
License-Expression: MIT
Keywords: automation,changelog,ci-cd,llm,mcp,openrouter,readme,todo
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: schedule
Requires-Dist: apscheduler>=3.10; extra == 'schedule'
Description-Content-Type: text/markdown

# taskill

> Daily project hygiene: keep `README.md` / `CHANGELOG.md` / `TODO.md` in sync with reality.
> LLM-first, algorithmic fallback. Works standalone, in CI, or via Ansible.

`taskill` is the small daemon you stop forgetting to run. Once a day (or whenever metrics drift), it reads your git log, your `SUMD.md` / `SUMR.md`, your coverage report, and updates the three documentation files everyone tells themselves they'll keep current and never do.

It uses an LLM where one is available — Windsurf MCP first (because you're probably already running it in JetBrains), OpenRouter second — and falls back to a deterministic Conventional Commits parser when no LLM is reachable. The fallback is always available and always runs offline.

`taskill` deliberately doesn't replace `pyqual`, `llx`, or `prefact`. It calls them as subprocesses when configured, picks up their reports, and stays out of the way otherwise.

## Install

```bash
pip install taskill                    # core
pip install "taskill[mcp]"             # with Windsurf MCP support
pip install "taskill[mcp,schedule]"    # with built-in scheduler
```

## Quickstart

```bash
cd your-project/
taskill init                  # writes taskill.yaml + .env.example
cp .env.example .env          # add OPENROUTER_API_KEY
taskill status                # preview without running
taskill run --dry-run         # see what would change
taskill run                   # do it
```

## What it does

Every run produces three (idempotent) edits:

1. **`CHANGELOG.md`** — appends new entries under `## [Unreleased]`, grouped by Conventional Commit type (`### Added`, `### Fixed`, `### Performance`, etc.). Uses [Keep a Changelog](https://keepachangelog.com/) layout. Existing entries are deduplicated.
2. **`TODO.md`** — moves completed items to a `## Done (moved to CHANGELOG)` section, and appends `TODO:` / `FIXME:` markers found in new commit bodies under `## Discovered`.
3. **`README.md`** — refreshes only the block between `<!-- taskill:status:start -->` and `<!-- taskill:status:end -->` markers (HEAD, coverage, failing tests, summary). Never touches the rest of the file.

## Provider chain

The chain runs top-to-bottom. First provider that's available *and* succeeds wins.

| Order | Provider | Used when |
|---|---|---|
| 1 | `windsurf_mcp` | `mcp` package installed and a Windsurf endpoint resolves |
| 2 | `openrouter` | `OPENROUTER_API_KEY` is set |
| 3 | `algorithmic` | always — pure git-log + Conventional Commits parser |

You can reorder, disable, or pass options via `taskill.yaml`:

```yaml
providers:
  - name: openrouter         # skip windsurf, go straight to OpenRouter
    enabled: true
  - name: algorithmic
    enabled: true
```

## Triggers

`taskill run` is a no-op unless one of the configured thresholds is crossed. State lives in `.taskill/state.json` so cron, GitHub Actions, and Ansible all share the same delta logic.

```yaml
triggers:
  min_hours_since_last_run: 24
  min_commits_since_last_run: 1
  changed_files_threshold: 1
  coverage_change_pct: 2.0       # absolute pp; null to disable
  failed_tests_changed: true
  watch_files: [SUMD.md, SUMR.md]
  require_all: false             # OR by default; set true for AND
```

`taskill run --force` ignores triggers entirely.

## Running it

### Cron / systemd timer

```cron
0 6 * * * cd /path/to/project && /usr/local/bin/taskill run >> ~/.taskill.log 2>&1
```

### GitHub Actions

See `examples/github-action.yml`. Triggers on `push` to main, runs `taskill run`, opens a PR if files changed.

### GitLab CI

See `examples/gitlab-ci.yml`. Same idea, with merge-request creation via the GitLab API.

### Ansible

See `examples/ansible-playbook.yml`. Useful for fleet-wide hygiene across many self-hosted repos.

## CLI

```
taskill init           # generate taskill.yaml + .env.example
taskill status         # show what would happen, no writes
taskill run            # execute (respects triggers)
taskill run --force    # ignore triggers
taskill run --dry-run  # don't write files or state
taskill run --json     # machine-readable output
taskill release X.Y.Z  # promote [Unreleased] → versioned heading
taskill clean-todo     # wipe TODO.md (after a release)
```

## Configuration reference

See [`taskill.yaml`](./taskill.yaml) at the repo root for the annotated default config.

## Reusing existing tools

`taskill` doesn't try to absorb `pyqual` / `llx` / `prefact`. It calls them by `subprocess` when toggled in `reuse:` and feeds their JSON output to the LLM as extra context:

```yaml
reuse:
  pyqual: true       # taskill will run `pyqual report --json`
  llx: false         # ...add llx context (planned for v0.2)
  prefact: false     # ...add prefact suggestions (planned for v0.2)
```

If a tool isn't on `PATH`, `taskill` skips it silently — no hard dependency.

## How it relates to the wider stack

```
SUMD (description) ─┐
                    ├─→ taskill ──→ README.md
git log ────────────┤              CHANGELOG.md
pyqual report ──────┤              TODO.md
SUMR (state) ───────┘
```

`taskill` reads, never generates code. That's what `prefact` / `llx` / `pyqual` are for.

## License

MIT — see [LICENSE](./LICENSE).

## Status

<!-- taskill:status:start -->
_Bootstrapped — no live project status yet. Will populate after first `taskill run`._
<!-- taskill:status:end -->