@taskset/cli 4.0.0 → 6.0.0

package/docs/_meta.ts

@@ -0,0 +1,9 @@
+export default {
+	index: 'Overview',
+	'getting-started': 'Getting Started',
+	configuration: 'Configuration',
+	'cli-reference': 'CLI Reference',
+	'task-files': 'Task Files',
+	'document-types': 'Document Types',
+	agents: 'For Agents',
+}

package/docs/agents/_meta.ts

@@ -0,0 +1,5 @@
+export default {
+	index: 'For Agents',
+	workflows: 'Agent Workflows',
+	commands: 'Agent Commands',
+}

package/docs/agents/commands.md

@@ -0,0 +1,70 @@
+---
+title: Use Taskset command contracts
+description: Machine-oriented contracts for discovery, JSON output, clear flags, search, and identifiers.
+contentType: Reference
+navLabel: Agent Commands
+---
+
+# Use Taskset command contracts
+
+This page quotes the contracts agents should rely on. For the full human reference, see [CLI reference](../cli-reference.md).
+
+## Discovery and defaults
+
+| Fact | Contract |
+| --- | --- |
+| Repository marker | Nearest ancestor `.taskset/` directory |
+| Optional config | `taskset.config.ts` beside that root |
+| Missing config | Built-in statuses, priorities, and defaults |
+| `taskset config --json` | Includes `rootDirectory`, `configPath`, `hasConfig`, `dataDirectory`, `config` |
+| `taskset init` | Creates `.taskset/`; `--config` writes optional config |
+
+## Output and exit codes
+
+- Stdout carries requested output
+- Stderr carries diagnostics and generation warnings
+- Exit `0` means success
+- Exit `1` means repository or domain failure
+- Exit `2` means usage or validation failure
+
+## Identifiers
+
+- Entity `id` values are immutable 5–6 character lowercase hex strings
+- Filenames are `{sequence}-{slug}-{id}.md`
+- Commands and relationships must use the short `id`
+- Never cite the mutable sequence prefix as identity
+
+## Array updates and clear flags
+
+Array options replace the whole stored array. Repeat the singular option once per desired value. Clear with the exact plural flag:
+
+- `--clear-dependencies`
+- `--clear-labels`
+- `--clear-assignees`
+- `--clear-reviewers`
+- `--clear-related`
+- `--clear-files`
+- `--clear-directories`
+- `--clear-projects`
+- `--clear-parent`
+- `--clear-owner`
+
+Do not guess a clear flag from the singular setter name.
+
+## Search and impact
+
+- `--search` is token-aware: every normalized term must match title or body
+- Terms may appear in any order
+- `--impact` expands file, directory, or dependency matches to dependent work
+
+## Document kinds
+
+Use only these kinds:
+
+- `story`
+- `flow`
+- `decision` (`adr`, `dr` aliases)
+- `research`
+- `runbook`
+
+Document statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and `archived`.

package/docs/agents/index.md

@@ -0,0 +1,99 @@
+---
+title: Operate Taskset as an agent
+description: Plan, research, decide, and track repository work with the Taskset CLI, skill, and JSON contracts.
+contentType: How-to
+navLabel: For Agents
+---
+
+# Operate Taskset as an agent
+
+Use this page when you are an agent operating Taskset in a repository. Humans should start with [Getting started](../getting-started.md). Maintainer architecture lives under [Maintainer docs](../maintainers/index.md).
+
+Taskset is not only a task tracker. You use it to capture plans, research, decisions, flows, runbooks, and the tasks that execute them in one Git-native graph.
+
+## Load the skill first
+
+Prefer the packaged skill before inventing workflow:
+
+```bash
+npx skills add FalseFoundation/taskset --skill taskset
+```
+
+Project and global skill installs both work. After a project npm install, offline copies also live at `node_modules/@taskset/cli/skills/taskset/SKILL.md`.
+
+## Invoke the CLI
+
+Do not assume `pnpm taskset`. Use whichever runner the environment provides:
+
+```bash
+npx @taskset/cli document list --json
+npx @taskset/cli task list --json
+pnpm dlx @taskset/cli doctor --json
+yarn dlx @taskset/cli document show your_document_id_here --json
+bunx @taskset/cli sync --json
+taskset task list --json
+```
+
+## Discover the repository
+
+1. Walk upward for `.taskset/`
+2. Load optional `taskset.config.ts` at that root when present
+3. Otherwise use built-in defaults
+
+No config file is required. `taskset init` creates `.taskset/` only. Pass `--config` when the repository wants an optional TypeScript overlay.
+
+## Choose the right artifact
+
+| If the work produces… | Create… |
+| --- | --- |
+| A user outcome or acceptance criteria | `story` |
+| A journey with variants and checks | `flow` |
+| Evidence, options, or a recommendation | `research` |
+| A lasting architectural or product choice | `decision` / `adr` |
+| A repeatable recovery or ops procedure | `runbook` |
+| Scoped execution with status and owners | `task` |
+
+Link documents and tasks with `--related`. Keep one-off scratch in the task body.
+
+## Core operating rules
+
+- Treat `.taskset/tasks/` and kind-specific document directories as the source of truth
+- Mutate through CLI commands when a command exists
+- Cite short hex ids such as `a1b2c3`, never filename sequence prefixes
+- Prefer `--json` for handoffs
+- Create follow-up tasks or checklist subtasks for newly discovered work
+- Create research, decision, runbook, story, or flow documents when work produces reusable evidence or lasting choices
+- Keep statuses current mid-work
+
+## Command map
+
+| Goal | Command |
+| --- | --- |
+| Inspect root and defaults | `taskset config --json` |
+| Validate repository | `taskset doctor --json` |
+| List or search tasks | `taskset task list --search "terms" --json` |
+| List or search documents | `taskset document list research --search "terms" --json` |
+| Show one entity | `taskset task show your_task_id_here --json` |
+| Create executable work | `taskset task create --title "Describe the work"` |
+| Create durable memory | `taskset document create research --title "Evaluate options" --related your_task_id_here` |
+| Change status | `taskset task status your_task_id_here doing` |
+| Impact query | `taskset task list --file path/or/dir --impact --json` |
+| Repair and rebuild | `taskset sync --json` |
+
+Full contracts: [CLI reference](../cli-reference.md) and [Agent command contracts](commands.md).
+
+## Workflow checklist
+
+1. Confirm the repository root with `taskset config --json`
+2. Search existing tasks and documents before creating duplicates
+3. Capture durable evidence or decisions as documents mid-work
+4. Create or update tasks for executable delivery
+5. Resolve ownership before mutating assigned work
+6. Keep statuses current, then re-validate after edits
+
+## Related pages
+
+- [Agent workflows](workflows.md)
+- [Agent command contracts](commands.md)
+- [Document types](../document-types.md)
+- [Task files](../task-files.md)

package/docs/agents/llms.txt

@@ -0,0 +1,28 @@
+# Taskset
+
+> Git-native Markdown workspace for planning, research, decisions, operations, and delivery.
+
+Taskset stores stories, flows, research, decisions, runbooks, and tasks under `.taskset/`. The CLI is published as `@taskset/cli` and runs through package runners or a global install. Config files are optional.
+
+## For agents
+
+- [Operate Taskset as an agent](https://taskset.false.foundation/docs/agents)
+- [Follow agent workflows](https://taskset.false.foundation/docs/agents/workflows)
+- [Use Taskset command contracts](https://taskset.false.foundation/docs/agents/commands)
+- [Choose a document type](https://taskset.false.foundation/docs/document-types)
+- [Understand task files](https://taskset.false.foundation/docs/task-files)
+- [CLI reference](https://taskset.false.foundation/docs/cli-reference)
+
+## For humans
+
+- [Keep the whole delivery story beside the code](https://taskset.false.foundation/docs)
+- [Start a Taskset repository](https://taskset.false.foundation/docs/getting-started)
+- [Configure Taskset defaults](https://taskset.false.foundation/docs/configuration)
+
+## Optional offline skill
+
+After install, load `node_modules/@taskset/cli/skills/taskset/SKILL.md`, or install with:
+
+```text
+npx skills add FalseFoundation/taskset --skill taskset
+```

package/docs/agents/workflows.md

@@ -0,0 +1,50 @@
+---
+title: Follow agent workflows in Taskset
+description: Ownership checks, mid-work updates, documents, and monorepo habits for agent operators.
+contentType: How-to
+navLabel: Agent Workflows
+---
+
+# Follow agent workflows in Taskset
+
+These workflows assume the CLI is available and `.taskset/` already exists. Initialize with `taskset init` when it does not. Use documents for durable memory and tasks for execution; link them so later agents inherit the full story.
+
+## Before you execute a task
+
+1. Run `taskset task show your_task_id_here --json`
+2. Resolve `git config --get user.name`
+3. Compare owner and assignees with that identity
+4. Pause for confirmation when another person owns or is exclusively assigned the task
+5. Check unresolved dependencies and blockers before status changes
+
+Matching ownership does not override blockers. A generic instruction such as “work on the next task” does not override another person’s assignment.
+
+## While you execute
+
+- Set the active task to `doing` when work starts
+- Create child tasks (`--parent`) or checklist items (`- [ ]`) for newly discovered work
+- Check off finished checklist items as `- [x]`
+- Mark finished child tasks `done`
+- Create research, decision, runbook, story, or flow documents when evidence or lasting choices appear
+- Link documents and tasks with `--related`
+- Update a primary skill when the session designates one and a lasting lesson emerges
+
+Do not leave discovered work only in chat.
+
+## Close-out
+
+1. Confirm acceptance criteria are met
+2. Confirm every tracked subtask is finished or intentionally resolved
+3. Set the parent task to `done`
+4. Run the repository’s relevant tests or `taskset doctor --json` when the change touched contracts or many files
+
+## Monorepo habits
+
+- Prefer declared package names and existing Taskset projects over directory-name guesses
+- Record `--depends-on` only for real execution prerequisites
+- Attach the narrowest accurate `--file` or `--directory` scopes
+- Validate the changed package and affected dependents
+
+## Batch and sync
+
+Use `taskset document batch manifest.json --json` for multi-document jobs. Use `taskset sync --json` after upgrades or when filenames, ids, or generated views need repair.