Skip to content
Skills Library
Management & product · Planning

task-forest

/task-forest

Maintains a repo-local task forest or task DAG for the current workspace. Use when the user asks to initialize or update a task forest, close a session, summarize evolving project work, align a request with a global goal, track progress/history/deviations/todos, save or apply a task proposal, or export the client-readable task-forest HTML. Do not use for executing the tracked tasks themselves or for generic HTML work.

Licence
MIT
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
14
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/task_forest.py, scripts/task_forest_html.py, scripts/task_forest_ordering.py, scripts/validate_task_forest_export.py

What it does and when to use it

Maintains a repo-local task forest or task DAG for the current workspace. Use when the user asks to initialize or update a task forest, close a session, summarize evolving project work, align a request with a global goal, track progress/history/deviations/todos, save or apply a task proposal, or export the client-readable task-forest HTML. Do not use for executing the tracked tasks themselves or for generic HTML work.

Original author description

Maintains a repo-local task forest or task DAG for the current workspace. Use when the user asks to initialize or update a task forest, close a session, summarize evolving project work, align a request with a global goal, track progress/history/deviations/todos, save or apply a task proposal, or export the client-readable task-forest HTML. Do not use for executing the tracked tasks themselves or for generic HTML work.

How it works

  1. Purpose
  2. Portability
  3. Core Rules
  4. Main Workflow
  5. Commands
  6. Outputs
  7. References and Validation
Original SKILL.md headings · 95 lines, 776 words
SKILL.md preview
---
name: task-forest
description: Maintains a repo-local task forest or task DAG for the current workspace. Use when the user asks to initialize or update a task forest, close a session, summarize evolving project work, align a request with a global goal, track progress/history/deviations/todos, save or apply a task proposal, or export the client-readable task-forest HTML. Do not use for executing the tracked tasks themselves or for generic HTML work.
---

# Task Forest

## Purpose

Maintain the current workspace's task structure, proposals, history, and progress. Produce one standalone HTML deliverable that a first-time reader can understand without opening another task list or internal file.

Use the user's language for task content, proposals, reports, and HTML. Default to Chinese when unknown.

## Portability

This skill is agent-agnostic. Install the whole `task-forest` directory in any host-supported skill location, then resolve scripts, references, and assets from the directory containing this `SKILL.md`. Do not assume a specific agent name, skill root, home-directory layout, shell, path separator, or operating system.

Use an available Python 3 launcher on the host (`python3`, `python`, or `py -3`). The scripts use the Python standard library and support macOS, Linux, and Windows. To label task history with the calling agent, set `COMPASS_AGENT_NAME` or `AGENT_NAME`, or pass `--actor`; otherwise the neutral value `agent` is used.

## Core Rules

1. Read and write task-forest data only through `scripts/task_forest.py`; never hand-edit `.agent-workbench/task-forest/` canonical files.
2. Use one primary `child_of` parent per node, `contributes_to` for secondary ownership, and `depends_on` for prerequisites.
3. Save graph changes as a proposal and wait for user confirmation before `proposal-apply --yes`.
4. Keep low-confidence inference in a question or proposal. Record material execution drift as a deviation.
5. Write visible task titles and purposes in plain language. A reader must understand what the task delivers, why it exists, and what has been completed without knowing internal codes such as `P04` or reading another file.
6. Export one HTML surface: `exports/task-forest.html`. It shows `done`, `in_progress`, and their necessary `child_of` ancestors, with history playback. Do not expose internal discussions, evidence, queues, filesystem paths, sessions, or proposal content in the HTML.
7. Keep HTML interactions read-only. Formal changes always return through the proposal workflow.
8. Keep task data and discovery metadata repo-local by default. Cross-workspace discovery is optional: enable it only after the user explicitly opts in by setting `TASK_FOREST_ENABLE_GLOBAL_REGISTRY=1`. This writes lightweight workspace paths and health summaries to `AGENT_WORKBENCH_DB`, or to `~/.agent-workbench/agent-workbench.sqlite3` when that variable is unset; it never stores task content.

## Main Workflow

When initializing, updating, or closing a session:

1. Run `init`.
2. Read `list --json` and `todo --json`.
3. Identify the global goal served by the session and the task structure that must remain visible.
4. When the workspace has an authoritative task list, preserve its meaningful `goal -> phase -> module -> concrete task` hierarchy and sibling order for every `done` or `in_progress` task. Include necessary ancestors, omit wholly unstarted branches, and attach extra fixes under the feature they improve. Never collapse several phases into one node or rely on edge creation order. If one sibling needs `display_order`, set a unique numeric value for the whole sibling group; partial, duplicate, or invalid values must fail validation.
5. Make every visible node independently understandable. Use a clear title plus `summary` or `purpose`; add outcomes or acceptance criteria when they clarify delivery. Treat internal codes as secondary labels, not as the task name.
6. Show and save a proposal. Do not apply it before confirmation.
7. After confirmation, run `proposal-apply --yes`, `validate`, and `export`.
8. Return the proposal path and the single HTML path.

Use `$task-clarifier` when user intent or the target global goal is genuinely unclear.

## Commands

Resolve `<skill-dir>` from this file and use an available Python 3 executable. The examples use `python3`; substitute the host's available launcher when needed.

```bash
python3 <skill-dir>/scripts/task_forest.py init
python3 <skill-dir>/scripts/task_forest.py list --json
python3 <skill-dir>/scripts/task_forest.py todo --json
python3 <skill-dir>/scripts/task_forest.py proposal-save --proposal-file /path/to/proposal.json
python3 <skill-dir>/scripts/task_forest.py proposal-apply <proposal-id> --yes
python3 <skill-dir>/scripts/task_forest.py validate
python3 <skill-dir>/scripts/task_forest.py export
```

The default workspace is the current directory. Use `--workspace` only when another workspace is explicit. Use `--root` only when the caller explicitly selected a non-default task-forest root.

Global registry integration is off by default. `TASK_FOREST_DISABLE_GLOBAL_REGISTRY=1` remains an explicit override when a host sets the enable flag globally.

## Outputs

The user-facing artifacts are:

```text
proposals/<proposal_id>.json
exports/task-forest.html
```

The exporter also maintains three internal compatibility files for `gap-router` and `local-agent-control-room`:

```text
exports/task-forest.graph.json
exports/task-forest.todos.json
exports/task-forest.timeline.json
```

Do not present those JSON files as delivery artifacts unless the user explicitly asks for machine-readable data.

## References and Validation

- Read `references/schema.md` for node fields, proposal actions, and canonical invariants.
- Read `references/goal-alignment.md` only when judging global-goal fit or competing candidate plans.
- Read `references/node-types.md` only when node classification is unclear.
- Read `references/concurrency.md` before resolving stale proposals or concurrent writes.
- Read `references/html-visualization-contract.md` when changing or validating the HTML.
- Read `references/integration-contract.md` only when changing JSON or registry compatibility.

For HTML or exporter changes, run:

```bash
python3 <skill-dir>/scripts/validate_task_forest_export.py --skill-dir <skill-dir>
```

The HTML remains a derived, read-only view. Canonical task data and proposal history stay repo-local.
Files in this package (14)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB
  • assets/task-forest-overview.html 42 KB
  • references/concurrency.md 4 KB
  • references/goal-alignment.md 5 KB
  • references/html-visualization-contract.md 4 KB
  • references/integration-contract.md 5 KB
  • references/node-types.md 1 KB
  • references/schema.md 10 KB
  • references/session-close-workflow.md 6 KB
  • scripts/task_forest.py 81 KB
  • scripts/task_forest_html.py 10 KB
  • scripts/task_forest_ordering.py 5 KB
  • scripts/validate_task_forest_export.py 38 KB

Versions

The database has no other skills named task-forest.

Database snapshot: 13.11.2026 · package version e57285ec092e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 84save-progress
    Save current project task progress to local task state file for cross-session continuity. Use when the user asks to save progress, uses an equivalent localized trigger phrase, the session is interrupted, or the user wants to resume work later. Writes to…
  • 90task-tracker
    Task tracking per project folder with an HTML board. Use for "track this", importing plan progress, resuming work, what is left/ready, task dependencies, the board, and every request where a [task-tracker] notice is present.
  • 96save-decisions
    Save the decisions, progress, and open work from the current session into the project's docs, so the session can be cleared without losing anything. Use when the user runs /save-decisions, or says "save decisions", "write down what we decided", or "before I clear".
  • 90build-tracker
    Live HTML progress page for multi-step work - current task with elapsed time, done tasks with durations, to-do tasks with estimates, overall ETA, updating in real time. Use when the user says "set up the build tracker", "track progress of this work", "show me task progress", or…
  • 100goal
    Set and track project goals. Triggered by "/goal" to define objectives, track milestones, or review progress.
  • 95kanbaa-task
    Create and move tasks on the Kanbaa to-do board in Herdr (Markdown files in the repo's to-do folder, with ids such as HER-12). Use when asked to add, create, file or log a task, to-do, ticket or follow-up for a repo; when work you are doing turns up something that should be…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.