@taskset/cli 4.0.0 → 5.1.0

package/skills/taskset-implement/references/architecture/ownership-and-dependencies.md

@@ -0,0 +1,107 @@
+# Ownership And Dependencies
+
+Repository ownership, package identity, dependency flow, and core runtime ownership.
+
+## Repository Ownership
+
+| Path | Ownership |
+| --- | --- |
+| `packages/contracts/` | Shared entity schemas, enums, DTOs, configuration types, and integration contracts; package `@taskset/contracts` |
+| `packages/utils/` | Reusable domain-light date, filesystem, path, Markdown, and frontmatter primitives; package `@taskset/utils` |
+| `packages/core/` | Entity operations, parsing orchestration, validation, storage, indexing, graph rules, search, filtering, project discovery, and impact analysis; package `@taskset/core` |
+| `packages/cli/` | Command-line adapter over core; package `@taskset/cli` |
+| `packages/tui/` | Keyboard-driven terminal interface over core; package `@taskset/tui` |
+| `packages/mcp/` | MCP tools and context bundles over core; package `@taskset/mcp` |
+| `packages/kanban/` | Web Kanban interface and board-specific presentation; package `@taskset/kanban` |
+| `packages/extension/` | VS Code integration, explorers, hovers, code lenses, and editor commands; package `@taskset/extension` |
+| `packages/configs/` | Shared TypeScript and tool configuration; package `@taskset/configs` |
+| `apps/office/` | Stakeholder dashboards, roadmaps, reports, and planning views; package `@taskset/office` |
+| `apps/www/` | Marketing site, public documentation, guides, and examples; package `@taskset/www` |
+| `docs/` | First-party repository and product documentation |
+| `skills/` | Agent-facing repository standards and workflows |
+
+Directory names and manifest package names must agree. Duplicate workspace
+package names are invalid. Treat a mismatch such as a `packages/core` manifest
+named `@taskset/cli` as a scaffold defect to fix, not an established identity.
+Every package and app has a `README.md` describing its purpose, owned behavior,
+and current implementation status.
+
+The publishable npm runtime is `@taskset/cli` and its dependency chain:
+`@taskset/core`, `@taskset/contracts`, and `@taskset/utils`. Other workspace
+packages and apps remain private until they have an intentional public
+contract. Recursive publication must preserve this runtime dependency closure.
+
+Do not add a top-level owner when an existing package or app already fits.
+Within an owning package, prefer responsibility-based names such as `config.ts`
+and `Config` over product-prefixed names such as `tasksetConfig.ts` and
+`TasksetConfig`. Reserve the Taskset name for public identity and protocol
+surfaces such as package names, the CLI command, `taskset.config.ts`, and
+`.taskset/`.
+
+Taskset dogfoods these boundaries. The root workspace installs core and CLI,
+loads `taskset.config.ts`, and stores its own planned work in `.taskset/tasks/`.
+
+## Dependency Flow
+
+The intended dependency direction is:
+
+```text
+configs
+
+contracts    utils
+    \         /
+       core
+        |
+cli  tui  mcp  extension  kanban  office
+
+www (product documentation and marketing; no domain authority)
+```
+
+Rules:
+
+- `contracts` must not depend on core or a client package.
+- `utils` must not depend on core or a client package.
+- `core` may depend on contracts and utils.
+- Product interfaces may depend on core and contracts.
+- A client package must not become the domain API for another client.
+- Apps may consume packages; shared packages must not depend on apps.
+- Keep framework-specific DTOs and view models in the owning interface unless
+  they are stable cross-interface contracts.
+- Import workspace code through manifest exports and declare it with
+  `workspace:*`.
+
+If a browser or editor runtime cannot access the filesystem directly, introduce
+a thin host adapter that delegates to core. Do not move domain rules into the
+transport layer.
+
+## Core Runtime Flow
+
+```text
+CLI / TUI / MCP / Extension / Kanban / Office
+                    |
+             @taskset/core API
+                    |
+       parse -> validate -> operate -> serialize
+                    |
+          canonical .taskset/ Markdown
+                    |
+       derived index / graph / generated views
+```
+
+Core owns behavior such as:
+
+- repository discovery and configuration loading
+- configuration validation and task creation defaults
+- entity parsing and validation
+- deterministic serialization
+- atomic create, update, move, and delete operations
+- status and lifecycle transitions
+- search and filtering
+- dependency and relationship graph construction
+- cycle and broken-reference detection
+- monorepo project and package discovery
+- code-path relationships and impact analysis
+- immutable snapshots, schema migrations, and generated metadata views
+
+Interfaces own input, rendering, transport, and user interaction. They call core
+operations rather than reproducing these rules.

package/skills/taskset-implement/references/architecture/product-and-source.md

@@ -0,0 +1,80 @@
+# Product And Source
+
+Product direction and the canonical source-of-truth model.
+
+## Product Direction
+
+Taskset began as an offline, inline, AI-friendly, human-readable task manager
+designed to accelerate software delivery and give development teams immediate
+awareness of the work surrounding their code.
+
+It grows from that core into a Git-native software delivery platform. Tasks,
+stories, flows, decisions, research, runbooks, and related project knowledge
+live beside the code as human-readable Markdown.
+
+Vision: become the Git-native operating system for software delivery.
+
+Mission: let developers, AI systems, and stakeholders work through different
+interfaces without creating a second source of truth outside the repository.
+
+Design for:
+
+- Markdown that remains useful without Taskset installed
+- Git history, branches, pull requests, and reviews as native workflows
+- deterministic machine-readable metadata with human-authored prose
+- monorepos and code-to-work relationships as first-class concepts
+- one domain engine shared by CLI, TUI, MCP, extension, web, and dashboards
+- local-first operation without preventing explicit hosted adapters
+- immediate team and AI awareness without a mandatory hosted service
+- replaceable indexes and generated views
+- explicit compatibility work that does not silently corrupt existing
+  repositories
+
+Near-term work should keep the task and supporting-document workflows coherent
+before inventing additional entity kinds or investing heavily in new interfaces.
+
+## Source-of-Truth Model
+
+Canonical project state lives under `.taskset/`.
+
+```text
+.taskset/
+├── tasks/
+│   └── .generated/          # disposable task metadata indexes
+├── stories/
+│   └── .generated/
+├── flows/
+│   └── .generated/
+├── decisions/
+│   └── .generated/
+├── research/
+│   └── .generated/
+├── runbooks/
+│   └── .generated/
+├── snapshots/
+└── cache/
+```
+
+Rules:
+
+- Entity Markdown files are authoritative persisted state.
+- `taskset.config.ts` is the discoverable repository usage configuration. It
+  controls validated behavior and defaults, not canonical entity state.
+- YAML frontmatter contains structured metadata. Markdown bodies contain
+  durable human context.
+- Do not store the same field independently in frontmatter and body.
+- Each entity folder owns its disposable `.generated/` indexes. `.taskset/cache/`
+  is also disposable. Neither is required to recover canonical state.
+- `snapshots/` contains immutable, non-authoritative safety checkpoints for
+  migrations and explicit restore workflows.
+- An in-memory index or optional on-disk cache may accelerate reads, but it must
+  be rebuildable from canonical files.
+- Do not introduce SQLite, a remote service, browser storage, editor global
+  state, or another hidden store as an undeclared authority.
+- Git is the versioning and collaboration layer around the files. Do not assume
+  it provides database transactions or conflict-free identifiers.
+- Repository discovery walks upward for exactly `taskset.config.ts`; canonical
+  storage remains fixed under `.taskset/`.
+
+Any persisted format change must define validation, compatibility, migration,
+and failure behavior before implementation.

package/skills/taskset-implement/references/architecture/storage-and-snapshots.md

@@ -0,0 +1,45 @@
+# Storage And Snapshots
+
+Storage, graph, and snapshot rules for canonical repository data.
+
+## Storage and Graph Rules
+
+- Parse frontmatter with a YAML parser and Markdown with a structured parser
+  where structure matters. Do not parse entity files with ad hoc regular
+  expressions.
+- Normalize stored code references to repository-relative POSIX paths.
+- Reject paths that escape the repository or `.taskset/` ownership boundary.
+- Keep IDs immutable. Do not adopt sequential IDs without a documented
+  branch-collision strategy.
+- Store one canonical direction for inverse relationships unless the schema
+  explicitly defines otherwise. Derive `blocks` from `dependsOn`, for example,
+  rather than allowing silent divergence.
+- Detect duplicate IDs, missing targets, invalid transitions, and dependency
+  cycles with actionable diagnostics.
+- Preserve meaningful Markdown content during metadata edits.
+- Never silently discard unknown or invalid data. Reject it or preserve it
+  according to an explicit schema policy.
+- Write through temporary files and atomic replacement where the platform
+  permits it. A failed update must not leave a truncated entity.
+- Make ordering deterministic where order has no domain meaning.
+
+## Snapshot Policy
+
+Git commits and branches are the normal history and rollback mechanism. Do not
+duplicate that history in a Taskset-owned snapshot database.
+
+The explicit snapshot capability is a safety mechanism for uncommitted state
+before migrations, restore operations, imports, repairs, or bulk mutation:
+
+- snapshots are user-invoked or created immediately before a destructive
+  operation
+- snapshots are immutable, timestamped, and content-addressable where practical
+- snapshots contain canonical Taskset files and enough metadata to explain why
+  they exist
+- snapshots are non-authoritative and may be deleted without changing current
+  project state
+- restore is explicit and conflict-aware
+- snapshots do not replace Git commits, reflogs, or normal backups
+
+Snapshot restore previews by default. Restore requires `--apply` and atomically
+reconciles canonical task files.

package/skills/taskset-implement/references/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+Use this file as the routing map for architecture standards. Load only the
+topic file needed for the change, then load additional files when the work
+crosses that boundary.
+
+## Routing
+
+- [product-and-source.md](architecture/product-and-source.md): product
+  direction, `.taskset/` source-of-truth rules, generated/cache authority, and
+  persisted format compatibility requirements
+- [ownership-and-dependencies.md](architecture/ownership-and-dependencies.md):
+  repository ownership, package identity, dependency flow, public runtime
+  package set, and core/interface ownership
+- [client-and-server.md](architecture/client-and-server.md): feature-based
+  clients, DDD-lite modular core/server architecture, and server composition
+  boundaries
+- [storage-and-snapshots.md](architecture/storage-and-snapshots.md): storage,
+  graph, canonical relationship, atomic write, and snapshot rules
+- [documentation-and-generated.md](architecture/documentation-and-generated.md):
+  documentation architecture, website content ownership, integrations, and
+  generated-source handling
+
+## Loading Guidance
+
+- For package boundaries, dependency direction, or public package behavior, load
+  `ownership-and-dependencies.md`.
+- For `.taskset/` persistence, schema compatibility, generated views, snapshots,
+  or filesystem mutation, load `product-and-source.md` plus
+  `storage-and-snapshots.md`.
+- For UI, CLI, MCP, extension, Kanban, Office, core, or server architecture,
+  load `ownership-and-dependencies.md` plus `client-and-server.md`.
+- For documentation routes, website content, blog ownership, or generated
+  outputs, load `documentation-and-generated.md`.

package/skills/taskset-implement/references/conventions/backend-and-tooling.md

@@ -0,0 +1,33 @@
+# Backend And Tooling
+
+Backend technology choices plus shell and automation conventions.
+
+## Backend Technology
+
+- Prefer TypeScript for services and hosted adapters.
+- Use NestJS when modules, dependency injection, guards, transport adapters, or
+  service scale justify it; do not add NestJS to a small composition root by
+  default.
+- With NestJS, prefer `class-transformer` and `class-validator` at transport DTO
+  boundaries.
+- Prefer TypeORM when an object-relational mapper is appropriate.
+- Use Rust for native executables or components with a concrete need for
+  systems performance, memory control, portability, or concurrency.
+- Prefer MariaDB for smaller hosted applications and PostgreSQL for larger or
+  more advanced relational workloads.
+- Keep database schemas, migrations, backup, and consistency behavior explicit.
+- No server or database replaces `.taskset/` Markdown as canonical Taskset
+  state.
+
+## Shell and Tooling
+
+- Start Bash scripts with `set -euo pipefail`.
+- Derive `repo_root` from the script location.
+- Quote paths and variable expansions.
+- Validate prerequisites before mutation.
+- Make setup and generation idempotent.
+- Use temporary directories and traps for cleanup.
+- Print concise, prefixed, actionable errors.
+- Keep automation with its owning package or a focused tooling directory when
+  one is introduced.
+- Do not add root scripts that duplicate package-manager or Turbo behavior.

package/skills/taskset-implement/references/conventions/design.md

@@ -0,0 +1,38 @@
+# Design Conventions
+
+General design principles for Taskset implementation work.
+
+## General Design
+
+- Apply SOLID as design heuristics, especially SRP, OCP, LSP, and DIP. Preserve
+  separation of concerns, encapsulation, high cohesion, low coupling,
+  testability, and inward dependency flow without creating ceremonial layers.
+- Prefer clean architecture boundaries and pragmatic DDD where domain behavior
+  benefits from explicit modules, entities, value objects, use cases, and
+  ports. Use feature-based architecture for user-facing and interaction
+  surfaces.
+- Prefer object-oriented design for stateful domain models, lifecycle-rich
+  entities, polymorphic adapters, and dependency-injected boundaries. Prefer
+  focused functions for stateless parsing, validation, serialization, and data
+  transformation. Do not convert code to classes for style alone.
+- Use in-process domain events when several independent reactions or clear
+  temporal decoupling justify them. Do not add an event bus, message broker, or
+  distributed event architecture without a measured product need.
+- Reuse before adding. Extend the existing source of truth when the concept
+  already exists.
+- Prefer explicit data flow, typed state, discriminated variants, and
+  structured errors over string coordination.
+- Keep functions and modules focused. Split by responsibility, not arbitrary
+  line count.
+- Separate pure parsing, validation, graph, and query logic from filesystem
+  effects where practical.
+- Fail with actionable diagnostics for invalid persisted state or destructive
+  operations.
+- Comment format constraints and non-obvious tradeoffs. Do not narrate obvious
+  code.
+- Add focused TSDoc to non-obvious public APIs and short orienting comments
+  around complex algorithms, transactions, migrations, synchronization, and
+  validation. Do not document obvious assignments or straightforward control
+  flow.
+- Keep diffs narrow. Do not combine behavior changes with unrelated renaming or
+  cleanup.

package/skills/taskset-implement/references/conventions/interfaces-and-ui.md

@@ -0,0 +1,50 @@
+# Interfaces And UI
+
+CLI, interface, UI, and frontend organization rules.
+
+## CLI and Interface Behavior
+
+- Keep CLI commands thin: parse arguments, call core, render results, map errors
+  to exit codes.
+- Current CLI commands are `taskset init`, `taskset config`, `taskset doctor`,
+  `taskset generate`, `taskset snapshot create`, `list`, `restore`, and
+  `taskset task create`, `list`, `show`, `update`, `status`, and `delete`.
+- Reserve stdout for requested output and stderr for diagnostics.
+- Avoid interactive prompts when flags or stdin make automation possible.
+- Provide deterministic structured output before integrations depend on parsing
+  decorative terminal text.
+- Keep TUI keyboard behavior and state in TUI, not core.
+- Keep MCP tool schemas close to MCP adapters while reusing domain schemas.
+- Keep extension commands and VS Code lifecycle behavior in the extension.
+- Keep filtering and graph semantics in core; clients may own only view-specific
+  sorting, grouping, and layout.
+
+## UI Organization
+
+Use TypeScript and React for web interfaces. Prefer TanStack's headless
+ecosystem when the feature needs the corresponding capability:
+
+- Query for server state and mutations
+- Form for complex validated forms
+- Table for tabular state
+- Hotkeys for keyboard commands
+- Pacer for debounce, throttle, queue, and rate-control behavior
+- Virtual for large virtualized collections
+- DB for a justified client-side reactive data layer
+- Devtools and library-specific devtools during development
+
+Adopt each package by demonstrated need. Do not install the full ecosystem in
+every app, use a large abstraction for trivial local state, or hide domain
+rules in client caches. Review maturity and API stability before using alpha or
+beta packages on critical paths.
+
+For Kanban and Office:
+
+- Organize by product feature, then colocate components, hooks, tests, and styles.
+- Keep server or host communication behind typed adapters.
+- Represent loading, empty, invalid-repository, stale, conflict, and error states
+  explicitly.
+- Preserve keyboard, focus, labels, roles, and screen-reader behavior.
+- Share UI through a dedicated package only after more than one surface needs a
+  stable visual contract.
+- Do not put React stores or UI dependencies in `@taskset/utils`.

package/skills/taskset-implement/references/conventions/naming-and-packages.md

@@ -0,0 +1,64 @@
+# Naming And Packages
+
+Naming, package identity, command naming, and configuration identity.
+
+## Naming and Package Identity
+
+- Directories: lowercase; use kebab-case for multiword names.
+- TypeScript modules: camelCase when named after behavior, kebab-case when the
+  local feature already uses it. Stay consistent within an owner.
+- React components and providers: `PascalCase.tsx`.
+- Hooks: `useThing.ts`; exported function `useThing`.
+- Variables and functions: `camelCase`.
+- Types, interfaces, classes, components, and schemas: `PascalCase`.
+- Stable protocol and schema constants: `UPPER_SNAKE_CASE`.
+- Colocated tests: source filename plus `.test.ts` or `.test.tsx`.
+- Integration and E2E specs: descriptive kebab-case ending in `.spec.ts`.
+- Shell scripts: kebab-case.
+- Name files and symbols for their responsibility inside the owning package.
+  Prefer `config.ts`, `Config`, and `Repository` over names prefixed with the
+  product or package name.
+- Keep the product name only where it is part of a public identity or protocol,
+  such as `taskset.config.ts`, `.taskset/`, the `taskset` command, package
+  names, and user-facing prose.
+
+Canonical workspace identities:
+
+```text
+@taskset/configs
+@taskset/contracts
+@taskset/utils
+@taskset/core
+@taskset/cli
+@taskset/tui
+@taskset/mcp
+@taskset/kanban
+@taskset/extension
+@taskset/office
+@taskset/www
+```
+
+`@taskset/cli`, `@taskset/core`, `@taskset/contracts`, and `@taskset/utils` are
+public npm packages. The remaining workspace identities are private until their
+owning interfaces are ready for independent release. Use `@taskset/cli` in
+installation and configuration examples. Use the other public package names
+when consumers intentionally use their lower-level APIs.
+
+Use the exact current manifest name in dependencies, filters, and Changesets.
+Package directories and names must agree. Fix duplicate or misplaced identities
+instead of documenting aliases for accidental scaffold state.
+
+Command names use lowercase kebab-case:
+
+```text
+taskset task list --file packages/core --impact
+taskset context-bundle
+```
+
+The root usage configuration is exactly `taskset.config.ts`. Export a
+versionless object, preferably through `defineConfig` from `@taskset/core`.
+Keep configuration fields behavioral; never use config to redirect canonical
+entity storage outside `.taskset/`.
+
+Entity field names use `camelCase`. Status, priority, and type values use stable
+lowercase tokens such as `doing`, `high`, and `feature`.

package/skills/taskset-implement/references/conventions/task-files.md

@@ -0,0 +1,89 @@
+# Task File Conventions
+
+Canonical Taskset entity metadata and Markdown file rules.
+
+## Taskset Entity Files
+
+Use YAML frontmatter for machine metadata and Markdown for human context:
+
+```markdown
+---
+id: 0000001-add-task-validation
+title: Add task validation
+status: doing
+priority: high
+order: 10
+createdAt: 2026-06-12
+updatedAt: 2026-06-12 09:30 UTC
+labels:
+  - core
+dependsOn: []
+files:
+  - packages/core/src/tasks/validateTask.ts
+---
+
+# Context
+
+Describe why the work exists.
+
+# Acceptance Criteria
+
+- [ ] Invalid statuses produce an actionable diagnostic.
+```
+
+Rules:
+
+- Require `id`, `title`, `status`, `createdAt`, and `updatedAt`.
+- Read and serialize one strict versionless task shape. Reject legacy
+  versioned task frontmatter instead of silently migrating or repairing it.
+- Accept people, planning, canonical relationship, path, and project metadata
+  only through the shared strict schema.
+- Use `todo`, `doing`, `blocked`, `done`, and `canceled` for task status.
+- Use `low`, `medium`, `high`, and `urgent` for task priority.
+- Priority is the sole measure of task importance. Do not add a second,
+  overlapping importance field.
+- `order` is the sole user-controlled sequence field. It is an optional finite
+  nonnegative number. Lower values sort first, missing values sort after
+  ordered tasks, and duplicate values fall back to task ID ordering.
+- Repository configuration may select and order the active values from that
+  vocabulary. Defaults and task creation must respect the configured list.
+- Define one canonical representation for each field.
+- Use repository-relative POSIX paths in persisted metadata.
+- Serialize new timestamps as `YYYY-MM-DD` or `YYYY-MM-DD HH:mm UTC`. Continue
+  reading the documented legacy ISO 8601 UTC form until a compatibility change
+  explicitly removes it.
+- Keep IDs immutable and compare them exactly.
+- Format new task IDs as a seven-digit sequence plus a lowercase title slug.
+  Keep legacy `TS-` ULIDs readable only so `task migrate-ids` can rewrite them
+  and all canonical relationships atomically.
+- Preserve user-authored body text and meaningful list order.
+- Use stable key ordering and one final newline in generated output.
+- Generated metadata indexes cover supported non-ID metadata fields, group
+  timestamp values by calendar date, and keep generated filenames readable
+  instead of URL-encoding spaces or path separators.
+- Omit absent optional fields consistently; do not alternate between missing,
+  empty, and `null` without schema meaning.
+- Validate enum values, dates, paths, IDs, and relationship targets centrally.
+- Validate normalized CLI arguments and public core inputs with Zod schemas.
+  Keep `parseArgs` limited to tokenization and use `superRefine` for
+  cross-option rules.
+- Do not infer `updatedAt` or lifecycle timestamps differently in each client.
+- Do not write derived inverse relationships into files unless the schema makes
+  them independently authoritative.
+- Keep `dependsOn`, `related`, `duplicates`, and `parent` canonical. Derive
+  `blockedBy`, `blocks`, `children`, and `subtasks`.
+- Treat schema additions, removals, defaults, and coercions as compatibility
+  decisions.
+- Reject unknown fields, duplicate list values, self-dependencies,
+  non-normalized paths, and an `updatedAt` value earlier than `createdAt`.
+- Never silently repair a file during a read. `doctor` may propose or perform
+  explicit fixes with user-visible output.
+
+Keep schemas and static contracts in `@taskset/contracts`. Keep parsing
+orchestration, defaults, transitions, validation policy, and migrations in
+`@taskset/core`. Keep generic YAML/Markdown mechanics in `@taskset/utils` only
+when they are not Taskset-specific.
+
+Put generic date, time, and mathematical operations in `@taskset/utils` when
+they have no task-domain policy. Prefer names such as `parseDate` over
+task-specific wrappers such as `parseTaskDate`.

package/skills/taskset-implement/references/conventions/tests-and-docs.md

@@ -0,0 +1,55 @@
+# Tests And Documentation
+
+Testing and documentation conventions.
+
+## Tests and Documentation
+
+- Use Vitest as the default TypeScript unit and integration test runner.
+- Use explicit imports from `vitest`; do not enable test globals repository-wide.
+- Prefer test-first development for domain rules, parser behavior, lifecycle
+  transitions, graph invariants, migrations, and bug regressions.
+- Do not force test-first ceremony for documentation, formatting, generated
+  configuration, or short-lived exploratory work.
+- Add regression coverage for bug fixes.
+- Test behavior and boundary contracts, not implementation trivia.
+- Use temporary directories for filesystem tests.
+- Use fixture repositories for Git, monorepo discovery, and path-impact tests.
+- Cover CRLF/LF, Unicode, empty bodies, malformed YAML, duplicate IDs, broken
+  links, cycles, and interrupted writes where relevant.
+- Verify parse/serialize round trips without losing Markdown.
+- Keep unit tests deterministic and independent of user Git configuration,
+  network services, wall-clock time, and the actual repository.
+- Mark integration prerequisites explicitly.
+- Use current paths and package names in documentation.
+- Keep user documentation in `docs/`; `apps/www` renders it.
+- Publish `docs/` and `skills/` with `@taskset/cli` so installed consumers can
+  load the same guidance from `node_modules/@taskset/cli/docs` and
+  `node_modules/@taskset/cli/skills`. The CLI build copies those trees; do not
+  hand-edit the copies under `packages/cli/`.
+- Keep chronological release and project posts in `apps/www/posts/`; require
+  `title`, `description`, and `date` frontmatter and register each route in the
+  website's post registry.
+- Keep contributor, architecture, ADR, testing, and technology documentation
+  in `docs/maintainers/`.
+- Render maintainer documentation through the website's dedicated
+  `/maintainers` route and keep it out of the primary usage-docs navigation.
+- Keep a concise `README.md` in each package and app describing ownership,
+  dependencies, and current contents.
+- Keep the root `README.md` focused on installing, configuring, and using
+  Taskset. Keep detailed repository work under `docs/maintainers/`; root
+  community files may provide short discovery links to that canonical guidance.
+- Write user docs for newcomers first through short examples and plain
+  language, then provide precise contracts and edge cases for advanced users.
+  Simplicity must not come from hiding important constraints.
+- Prefer `.md` for content. Use `.mdx` only when interactive React content is
+  required.
+- Include `title` and `description` frontmatter on pages rendered by the docs
+  site.
+- Keep product plans distinct from executable specifications.
+- Update docs when commands, persisted formats, or public package contracts
+  change.
+- Update `skills/taskset-implement/` in the same change when these repository standards
+  or workflows change.
+- When a workspace task finishes, update its canonical Taskset task through the
+  CLI when supported, then update affected user docs, maintainer docs, tests,
+  and standards before declaring the work complete.

package/skills/taskset-implement/references/conventions/typescript-and-exports.md

@@ -0,0 +1,41 @@
+# TypeScript And Exports
+
+TypeScript, formatting, import, export, and package-boundary rules.
+
+## TypeScript and Exports
+
+Root `biome.json` controls formatting:
+
+- tabs
+- 100-column target
+- single quotes
+- no semicolons
+- trailing commas
+- bracket spacing
+
+Follow these rules:
+
+- Keep strict TypeScript enabled.
+- Use `unknown` at filesystem, YAML, JSON, Git, process, and network boundaries,
+  then validate and narrow it.
+- Avoid `any`; contain unavoidable casts at the boundary.
+- Use `import type` or inline type imports for type-only dependencies.
+- Prefer extensionless package imports. Use `.ts` or `.tsx` for relative source
+  imports; TypeScript rewrites them to `.js` during emit. Write `.js` in source
+  only when a runtime or external contract requires it.
+- Prefer named exports and explicit package entrypoints.
+- Declare every imported package in the importing package's `package.json`.
+- Use `workspace:*` for internal dependencies.
+- Import shared code through package exports such as `@taskset/core` or an
+  explicit subpath. Never import a sibling package's `src/`.
+- Do not use TypeScript `paths` to imitate package exports or reach another
+  package's `node_modules`.
+- Keep public data immutable where mutation is not part of the contract.
+- Represent expected failures with typed errors or result variants. Include the
+  entity path, field, and remediation when useful.
+- Do not leak a CLI parser, UI framework, MCP SDK, or filesystem library type
+  into domain contracts.
+
+Shared configuration is consumed through `@taskset/configs` exports. Extend
+those exports when a preset is genuinely reusable; keep app-specific settings
+with the app.