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.
- Author
- dongshuyan ↗
- Repository
- compass-skills ↗
- Licence
- MIT
- Last repository change
- 19.10.2026
Assessment and security
- Files in this package
- 14
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
- Purpose
- Portability
- Core Rules
- Main Workflow
- Commands
- Outputs
- References and Validation
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…