beco/QualKard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.0 -- README rewrite (study workflow, board, badge, deps) + release bump (v1.0.0)

Browse Source
This commit is contained in:
Ruben Carlo Benante
2026-07-11 16:06:17 -03:00
parent 374517496a
commit 88a271e5b8
3 changed files with 115 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
README.md
View File

@@ -1,66 +1,132 @@
# Skeleton -- a Kanboard plugin template
# QualKard -- flashcard spaced repetition on your Kanboard
A minimal, working Kanboard plugin that you copy and rename as the starting point for a
real plugin. By itself it does only one trivial thing: it renders the word "Skeleton" at
the top of every page. It changes no data and runs no database migration.
Turn a Kanboard board into a spaced-repetition flashcard deck. Each card is a flashcard --
title is the prompt, description is the answer. You study a card, grade how it went by
dragging it into a grade column, and QualKard schedules when it should come back. Cards you
find easy drift far into the future; hairy ones return tomorrow.
## What it demonstrates
The scheduling math is ported from Ruben's C program **qualcard** (the "K" here just marks the
Kanboard port). The card movement -- bringing a card back when it falls due -- is done by the
companion **RecoReco** plugin, so QualKard needs RecoReco installed and RecoReco's cron running.
- A complete `Plugin.php` registration class with all the metadata Kanboard shows in
Settings -> Plugins (name, description, author, version, homepage, compatible version).
- A template hook (`template:layout:top`) that injects a template into the page.
- Asset hooks (`template:layout:css` and `template:layout:js`) that load a stylesheet and
a script. They are empty for now but prove the injection path works -- handy when a real
plugin needs custom CSS or JS.
- The standard plugin directory layout, with stub folders (`Controller/`, `Model/`,
`Schema/`, `Locale/`, `Test/`) ready to grow into.
QualKard is **opt-in per board**: installing it changes nothing until a project manager sets a
specific board up under Settings -> Integrations. Setting a board up **restructures its
columns**, so it is a deliberate, confirmed action -- see below.
## The study board
Setting a board up gives it exactly seven columns, each with a fixed role:
```
Drafts | Study | Hairy | Hard | Medium | Easy | Done
```
- **Drafts** -- where new and reset cards wait. A draft is inert: it never comes due on its own.
- **Study** -- the review queue. RecoReco moves a card here when it falls due; this column is
itself the "overdue" backlog, so it can hold more than one day's worth.
- **Hairy / Hard / Medium / Easy** -- the four grade columns. You review a card in Study, then
drag it into one of these to record how it went.
- **Done** -- a resting place you drag a card to when you want it out of rotation. A card in Done
does not come back (it is the one column that does not re-trigger).
## Studying
1. Read the prompt (the card title) in **Study**, recall the answer, then open the card to check
the description.
2. Drag the card into the grade column that matches how it went:
| Column | Meaning | Score |
|--------|---------|------:|
| Hairy | no idea / wrong | 0.0 |
| Hard | right, but a struggle | 1.3 |
| Medium | right, some effort | 3.0 |
| Easy | instant | 5.0 |
3. QualKard folds that score into the card's running average and sets the card's **due date** the
right number of days out (1 day for a hairy average, up to 11 for a mastered one). RecoReco
picks the card up from the grade column and, when it next falls due, moves it back to **Study**.
You never edit a due date or move a card back yourself -- grading is the only action.
### How the schedule is computed
Each card keeps a running average of its scores. A brand-new card is seeded a little below its
first score; after that the average is the mean of the old average and the new score. The average
maps to an interval:
| Average | Interval |
|------------|---------:|
| <= 0.60 | 1 day |
| <= 1.35 | 2 days |
| <= 2.20 | 3 days |
| <= 3.05 | 5 days |
| <= 3.90 | 7 days |
| <= 4.92 | 9 days |
| otherwise | 11 days |
So a card you keep grading Easy climbs toward an 11-day gap, while one you keep missing stays at a
day or two until it sticks.
## The mastery badge
Each card shows a small badge under its title, on the board and at the top of the opened card:
- **new** (yellow) -- an unread card that has never been graded.
- a **percent** of mastery (the average as a fraction of 5), coloured **red** below 50%,
**green** through 89%, and **blue** at 90% and up.
## Requirements
- Kanboard >= 1.2.0
- The **RecoReco** plugin, installed and enabled, with its cron task running (RecoReco is what
moves due cards back to Study). QualKard's setup button stays disabled until RecoReco is present.
QualKard refuses to set up a board that has **FinanceBuddy** enabled: the restructure would wreck a
finance board's columns. Disable FinanceBuddy on that board first, or use a different board.
## Installation
No build step and no dependencies.
Copy this folder into your Kanboard installation as `plugins/QualKard/`. The directory name must be
exactly `QualKard` (Kanboard derives the plugin namespace from the folder name). No build step and
no database migration.
1. Copy this folder into your Kanboard installation as `plugins/Skeleton/`.
2. Reload any page. The word "Skeleton" appears at the top.
3. Confirm it under Settings -> Plugins.
Then, on the board you want to study:
To uninstall, delete `plugins/Skeleton/`. Nothing else is left behind.
1. Go to Settings -> Integrations.
2. Under QualKard, click **Set up QualKard study board**, and confirm. This renames the board's
columns to the seven roles above (creating or removing columns to reach exactly seven) and moves
every existing card into Drafts.
3. Make sure RecoReco's cron is running so due cards come back.
## Directory layout
From the same page you can later **Reset all cards** (send every card back to Drafts, unread) or
**Disable QualKard machinery** (stop the automation without touching your columns or cards).
```
Skeleton/
Plugin.php Registration and hook wiring (the only required file).
README.md
LICENSE AGPL-3.0.
Template/
layout/header.php The visible "Skeleton" word.
Asset/
css/skeleton.css Loaded via template:layout:css.
js/skeleton.js Loaded via template:layout:js.
Controller/ Stub for future request handlers.
Model/ Stub for future business logic / DB access.
Schema/ Stub for future database migrations.
Locale/ Stub for future translations (e.g. pt_BR/, fr_FR/).
Test/ Stub for future unit tests.
```
## How it stores data
## How to fork this into a new plugin
1. Copy the folder and rename it, e.g. `plugins/MyPlugin/`. The folder name must match the
namespace and start with a capital letter.
2. In `Plugin.php`, change the namespace from `Kanboard\Plugin\Skeleton` to
`Kanboard\Plugin\MyPlugin`.
3. Update the metadata methods (`getPluginName`, `getPluginDescription`, `getPluginAuthor`,
`getPluginVersion`, `getPluginHomepage`, `getCompatibleVersion`).
4. Update the hook target paths: the lowercase prefix in `'skeleton:layout/header'` and the
`plugins/Skeleton/Asset/...` asset paths must match the new plugin name.
5. Replace `Template/layout/header.php` with your real template, or attach to a different
hook. See the Kanboard plugin hooks documentation for the full list of hook points.
No database migration. The per-board enable flag and the seven column roles are stored in project
metadata; each card's running average lives in task metadata, and QualKard writes the card's due
date and RecoReco's per-card recurrence config. Uninstalling the plugin leaves that metadata
harmlessly in place -- your columns and cards are untouched.
## License
AGPL-3.0. See LICENSE.
## More Kanboard plugins by Ruben (drbeco)
All free and AGPL-3.0, at [code.beco.cc](https://code.beco.cc/beco):
- **[RecoReco](https://code.beco.cc/beco/RecoReco)** -- calendar-scheduled recurring cards (yearly,
monthly, weekly, daily), driven by the card due date. QualKard rides RecoReco's move engine to
bring due flashcards back to the Study column.
- **[FinanceBuddy](https://code.beco.cc/beco/FinanceBuddy)** -- attach a money value to each card,
show it on the card, and total it per column, so a board can double as a simple finance board.
- **[OrganonTweaks](https://code.beco.cc/beco/OrganonTweaks)** -- an umbrella of small
quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due
dates, extra search keywords and shared board filters, and more.
- **[BulkMoveTasks](https://code.beco.cc/beco/BulkMoveTasks)** -- move every task from one board
column to another in a single action.
- **[ShrinkVertically](https://code.beco.cc/beco/ShrinkVertically)** -- shrink vertically-collapsed
board columns so the horizontal scrollbar stays within reach.
- **[TweakDrag](https://code.beco.cc/beco/TweakDrag)** -- board drag and touch niceties:
drag-to-scroll, a wider column gap, and smoother card dragging.