@taskset/cli 4.0.0 → 6.0.0

package/skills/taskset/references/task-modeling-examples.md

@@ -0,0 +1,249 @@
+# Task Modeling Examples
+
+Use these examples to choose task boundaries and metadata. The IDs in commands are placeholders for IDs returned by Taskset.
+
+## Split Independent Deliverables
+
+Bad: one task titled `Do auth, docs, dashboard, and tests` with the entire prompt copied into its body. It hides ownership, progress, and sequencing.
+
+Good: create separate tasks for the API, dashboard, and documentation when each produces a distinct outcome. Attach their relevant project and labels, and connect only genuine prerequisites.
+
+```bash
+pnpm taskset task create --title "Expose session-expiry API" --project api --label auth
+pnpm taskset task create --title "Show expired sessions in the dashboard" --project web --label auth --depends-on <api-task-id>
+pnpm taskset task create --title "Document session-expiry behavior" --project docs --related <api-task-id>
+```
+
+The dashboard is blocked by the API contract, so it depends on the API task. Documentation is related but need not be blocked if it can be drafted from the agreed contract.
+
+## Do Not Treat Prompt Order as Execution Order
+
+Prompt: “Update the UI, define the migration, then add the backend field.”
+
+Bad: make the migration depend on the UI because the UI appeared first.
+
+Good: infer that the schema/migration and backend field are prerequisites for the UI when repository evidence supports that flow. Create prerequisite tasks first, then use their returned IDs in `--depends-on` for downstream work. If the UI can use a stable mocked contract, relate the tasks instead of inventing a blocker.
+
+## Checklist or Child Task
+
+Both forms are subtasks. Prefer checklist items for steps that share one outcome; use Taskset child tasks when a step needs independent tracking.
+
+Bad: create separately tracked tasks for tiny steps that share one outcome:
+
+- Rename the function.
+- Update one import.
+- Run the focused test.
+
+Good: keep them as checklist items in the body of one outcome-oriented task:
+
+```markdown
+Rename the parser entrypoint without changing its public behavior.
+
+## Checklist
+
+- [ ] Rename the function and its imports
+- [ ] Update focused tests
+- [ ] Run the parser test suite
+
+## Acceptance criteria
+
+- The old symbol has no remaining callers.
+- Parser tests pass without behavior changes.
+```
+
+Use a child task with `--parent <parent-task-id>` instead if a step needs independent assignment, status, acceptance criteria, dependencies, or history.
+
+## Create Follow-Ups While Executing
+
+Bad: while fixing a parser bug, discover a missing migration and a docs gap, finish the parser fix, and leave those findings only in the chat transcript.
+
+Good: create Taskset follow-ups as soon as the work is clear. Use a child task when the new work belongs under the current outcome; create a sibling or related task when it is a distinct deliverable.
+
+```bash
+pnpm taskset task create --title "Add migration for parser id format" --parent <parser-task-id> --depends-on <parser-task-id>
+pnpm taskset task create --title "Document parser id format change" --project docs --related <parser-task-id>
+```
+
+Do not close or abandon the current task without recording discovered follow-up work in Taskset.
+
+## Keep Status Current Through Execution
+
+In this skill, "subtask" covers both Taskset child tasks and Markdown checklist items in a parent task body.
+
+Bad: start implementation, finish three child tasks and several checklist steps, and leave the parent stuck in `todo` or `doing` with unchecked `- [ ]` items until a final cleanup pass—or mark the parent `done` while children or checklist items are still open.
+
+Good: update progress as work proceeds.
+
+```bash
+pnpm taskset task update <parent-task-id> --status doing
+pnpm taskset task update <child-task-id> --status doing
+# ... complete that child task's acceptance criteria ...
+pnpm taskset task status <child-task-id> done
+```
+
+For checklist subtasks, flip completed items from `- [ ]` to `- [x]` in the parent body as soon as each step finishes. After every tracked subtask is complete (children `done`, checklist items checked) and the parent criteria pass:
+
+```bash
+pnpm taskset task status <parent-task-id> done
+```
+
+Every completed subtask must be marked finished—child tasks via `done`, checklist items via `- [x]`. Update statuses and checklist state mid-work when progress or blockers change; do not wait until the session ends.
+
+## Capture Lasting Lessons in the Primary Skill
+
+Bad: after three failed attempts, discover that Biome must run before the focused package test, close the task with that note in its body, and leave the session's primary skill unchanged so the next agent repeats the same failure.
+
+Good: when the repository or session treats a skill as primary, fold the durable rule into that skill (or its references) as a short decision rule—for example preferred tool selection, a known failure mode and its fix, or an architecture constraint. Keep task-specific history in the task; keep reusable guidance in the skill.
+
+Update the primary skill for lessons that future work should consider: tool or command choice, bug-fix patterns, repeated failures, and architecture decisions. Skip skill edits for one-off, task-local details that will not help later sessions.
+
+## Dependencies Versus Related Work
+
+Bad: connect every task about authentication with `--depends-on`. Shared subject matter is not a blocker and can create false chains or cycles.
+
+Good:
+
+- Use `--depends-on <task-id>` when this task cannot begin or complete until that task delivers an input.
+- Use `--related <task-id>` when tasks share context but can progress independently.
+- Use `--parent <task-id>` for decomposition, not execution order. Add `--depends-on` separately if a child is genuinely blocked.
+
+## References Belong in the Relevant Body
+
+Prompt: “Adopt Zod 4 for request validation; follow https://zod.dev/v4.”
+
+Bad:
+
+```markdown
+Upgrade validation.
+```
+
+Good:
+
+```markdown
+Adopt Zod 4 for request validation while preserving current error responses.
+
+## Acceptance criteria
+
+- Request schemas use the supported Zod 4 APIs.
+- Existing error-response contract tests pass.
+
+## References
+
+- [Zod 4 documentation](https://zod.dev/v4) — migration and API reference supplied by the user.
+```
+
+Copy the reference only into tasks where it informs the work, and retain the user's stated reason or constraint rather than saving a bare URL.
+
+## Update Without Clobbering Context
+
+Bad: replace an existing body merely to change status, losing checked items, acceptance criteria, and references; or mark the task done because code was written even though validation remains unchecked.
+
+Good: inspect the current task, apply the smallest update, preserve unrelated metadata, and reconcile the body with reality. Check completed checklist items, keep unfinished ones open, update relationships if scope changed, and set `done` only after the acceptance criteria are met.
+
+## Avoid Duplicate Work
+
+Bad: create `Add retry handling` without checking whether an active retry task already exists.
+
+Good: search current and recent tasks first. If the same outcome exists, update that task. If the new work is distinct but adjacent, create it and use `--related`. If a duplicate was already created and must remain for history, mark the duplicate relationship with `--duplicate` according to repository convention.
+
+## Record Repository Scope
+
+Bad: label a task `core` but omit the known paths, making file-impact searches unable to connect it to the affected code.
+
+Good: attach the narrowest established scope:
+
+```bash
+pnpm taskset task create --title "Validate task dependency cycles" --project core --file packages/core/src/graph/taskGraph.ts
+```
+
+Use `--directory` when the outcome genuinely spans a directory. Do not attach broad directories merely because the exact implementation is not yet known.
+
+## Recover From a Partial Batch
+
+Bad: five creates were requested, the third command failed, and the agent reruns all five commands. The first two tasks now exist twice.
+
+Good: retain the IDs and JSON output from successful creates, list the current tasks after the failure, then create or update only the missing work. Rebuild downstream `--depends-on`, `--related`, and `--parent` arguments from verified IDs rather than assumed command positions.
+
+## Close Rather Than Erase History
+
+Bad: delete a completed task to clean up the active list, or use `--remove-dependencies` without inspecting downstream tasks.
+
+Good: mark work `done` when its acceptance criteria pass. If work is superseded or duplicated, preserve the task and express that relationship according to repository convention. Delete only when removal itself is intended and its dependency impact has been inspected.
+
+## Owner and Assignees
+
+Bad: omit ownership from every generated task, assign every task to every contributor mentioned in the prompt, or overwrite an explicitly assigned owner with the local Git identity.
+
+Good: first resolve the repository's current Git user:
+
+```bash
+git config --get user.name
+```
+
+Use that value as the default owner when creating a task. If it returns `Alex Chen` and Alex will also implement the work:
+
+```bash
+pnpm taskset task create --title "Validate task dependency cycles" --owner "Alex Chen" --assignee "Alex Chen"
+```
+
+If the prompt explicitly makes Sam accountable while Alex implements it, preserve that distinction:
+
+```bash
+pnpm taskset task create --title "Validate task dependency cycles" --owner "Sam Rivera" --assignee "Alex Chen"
+```
+
+Use multiple `--assignee` options only when each named person is genuinely expected to execute part of the task. Code ownership, package maintainership, or prior review can inform investigation, but does not by itself authorize assigning a person.
+
+When a cross-package plan is split, choose owner and assignees per resulting task rather than copying the parent task's people blindly. Do not change existing ownership while updating unrelated metadata.
+
+## Pre-Execution Ownership Check
+
+Current Git user: `Alex Chen`.
+
+### Current User Is Assigned
+
+Task metadata:
+
+```yaml
+owner: Sam Rivera
+assignees:
+  - Alex Chen
+```
+
+Good: Alex may execute the task because Alex is an explicit assignee. Keep Sam as owner unless the user requests an accountability change.
+
+Bad: stop merely because owner and assignee differ, or replace Sam with Alex automatically.
+
+### Task Belongs to Someone Else
+
+Task metadata:
+
+```yaml
+owner: Sam Rivera
+assignees:
+  - Priya Shah
+```
+
+Prompt: “Work on the next open task.”
+
+Good: inspect and report the task, then ask whether Alex should proceed or take it over before changing status, assignment, task contents, or repository code.
+
+Bad: treat the generic prompt as permission, set the task to `doing`, add Alex as an assignee, or start implementation without surfacing the ownership conflict.
+
+### Specific Execution Is Explicitly Authorized
+
+Task metadata still names Sam and Priya, but the user says: “Alex, implement `TS-...` now; do not reassign it.”
+
+Good: this explicitly authorizes execution of the identified task. Proceed while preserving its owner and assignees as directed.
+
+Bad: ask the same execution question again, or interpret authorization to execute as authorization to replace the owner.
+
+### Takeover Includes Assignment Change
+
+The user says: “Take over `TS-...` and assign it to the current Git user.”
+
+Good: preserve the existing owner unless the user also requests an owner change, add or replace assignees according to the explicit instruction and repository convention, then begin work.
+
+Bad: silently transfer ownership as well, or retain an assignee list that no longer represents who is expected to perform the task.
+
+Read-only task inspection is allowed in every scenario above. The confirmation gate applies before mutations or execution, and it does not bypass unresolved dependencies or explicit blockers.

package/skills/taskset-implement/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: taskset-implement
+description: Repository-specific engineering standards for Taskset. Use when planning, implementing, reviewing, testing, documenting, releasing, or restructuring this repository, especially for the offline Git-native Markdown data model, package ownership, feature-based clients, DDD-lite modular core and server code, pnpm and Turbo workflows, TypeScript conventions, tests, and Changesets.
+---
+
+# Taskset Implementation Standards
+
+Apply these standards to every Taskset repository task. Treat them as decision
+rules, not as a substitute for reading the code involved.
+
+## Skill Resources
+
+Load only the references relevant to the task. The top-level reference files
+are routing maps; after reading the relevant map, load only the topic files it
+names for the work in front of you:
+
+- [architecture.md](references/architecture.md): route to product/source,
+  ownership/dependency, client/server, storage/snapshot, documentation, and
+  generated-source architecture references
+- [conventions.md](references/conventions.md): route to design, naming,
+  TypeScript, task entity, interface/UI, backend/tooling, test, and
+  documentation convention references
+- [workflows.md](references/workflows.md): route to environment, pnpm, Turbo,
+  dependency, docs-site, validation, Vitest, persisted-data, and Git workflow
+  references
+- [release.md](references/release.md): Changesets, compatibility, commit
+  language, and completion requirements
+- [`docs/maintainers/technology.md`](../../docs/maintainers/technology.md): preferred
+  TanStack frontend tools, TypeScript/NestJS and Rust backend choices, and
+  MariaDB/PostgreSQL database defaults
+
+If a referenced skill file does not exist, report the missing file, state which
+decisions cannot be made without it, and continue only with rules defined in
+this skill; do not infer conventions from absence.
+
+`agents/openai.yaml` is discovery and UI metadata. Do not load it as an
+instruction reference.
+
+## Start With Judgment
+
+1. Read the complete request before planning or acting. For a multi-part
+   request, identify dependencies, contradictions, and shared owners across all
+   items before changing any one item.
+2. Turn multi-part work into a prioritized checklist. Close every requested
+   item as implemented, already satisfied, or intentionally unnecessary with a
+   concrete reason; do not silently drop notes or late dependencies.
+3. Parse the request into intent, constraints, affected owners, and a concrete
+   completion condition.
+4. Inspect the worktree, manifests, relevant implementation, tests, and
+   executable configuration before proposing or editing.
+5. Challenge an approach that creates a second source of truth, bypasses core
+   validation, weakens deterministic file behavior, or crosses package
+   ownership without a contract.
+6. If a requested change appears unreasonable, internally contradictory,
+  destructive, or incompatible with established product contracts, explain
+  the concrete concern and ask for explicit confirmation before implementing
+  it. If the request still does not yield a concrete completion condition,
+  ask one focused question about the single most consequential missing piece
+  before implementing anything.
+7. Recover decisions from the repository before asking questions. Ask only when
+   a consequential product or data-format decision remains unresolved.
+8. Treat related work as one dependency graph. Keep schemas, core behavior,
+   clients, tests, docs, and release metadata consistent.
+9. Update this skill and its relevant references in the same change whenever
+   authoritative paths, package names, commands, architecture, product
+   contracts, documentation workflows, or completion rules change. Never leave
+   the skill knowingly stale.
+
+Do not implement a request merely because it was requested. Establish that the
+outcome is coherent with Taskset's Git-native contract first.
+
+## Establish Authority
+
+When repository sources disagree, use this order:
+
+1. Current user constraints and the actual task.
+2. Executable manifests and tooling: `package.json`, `pnpm-workspace.yaml`,
+   `turbo.json`, `tsconfig.json`, and `biome.json`.
+3. Current implementation and tests.
+4. Current first-party documentation and this skill.
+5. Product plans and historical notes for intent only.
+
+If current user constraints conflict with a non-negotiable product invariant
+listed in Preserve Product Invariants, the invariant takes precedence. Explain
+the conflict to the user and request an explicit override with rationale before
+proceeding.
+
+Do not turn accidental manifest mistakes, empty packages, or placeholder
+dependencies into conventions. Report them and follow the intended
+`@taskset/<directory-name>` ownership model.
+
+## Preserve Product Invariants
+
+Read [architecture.md](references/architecture.md), then the task-relevant
+architecture topic file, before changing package boundaries, entity formats,
+filesystem behavior, graph semantics, or interface contracts.
+
+Non-negotiable rules:
+
+- Human-readable files under `.taskset/` are the persistent source of truth.
+- Git provides history, transport, branching, and review; hidden databases do
+  not become authoritative.
+- Generated views, caches, and in-memory indexes are disposable and rebuildable
+  from canonical files.
+- `@taskset/core` owns domain behavior, parsing orchestration, validation,
+  filesystem mutation, indexing, graph rules, search, and lifecycle transitions.
+- CLI, TUI, MCP, extension, Kanban, and Office are interfaces over the same core
+  contracts. They do not reimplement Taskset semantics.
+- `@taskset/contracts` owns shared runtime schemas and TypeScript contracts
+  without filesystem, lifecycle, or UI behavior.
+- `@taskset/utils` stays domain-light. Task graph policy and entity lifecycle
+  logic belong in core.
+- External integrations are adapters and synchronized views. They do not become
+  the silent source of truth.
+- Persisted format changes require explicit compatibility and migration
+  decisions.
+- Canonical task files use one strict versionless metadata shape. Versioned
+  task frontmatter and unknown fields are rejected.
+- Canonical supporting documents live in kind-specific `.taskset/` directories:
+  stories, flows, decisions, research, and runbooks. Use their shared strict
+  metadata (aligned with task planning, people, path, and relationship fields)
+  and kind-specific body templates instead of modeling every durable document
+  as a task. Documents expose the same create, update, status, delete, list
+  query, search, impact, and derived-relationship operations as tasks, with
+  document-specific statuses.
+- Document mutations, imports, exports, and batches belong to core. The CLI
+  validates manifests and renders output only. Use TanStack Pacer for bounded
+  heavy batches and migrations, emit count and percentage progress, preserve
+  manifest result order, and serialize writes that allocate short hex IDs plus
+  filename display sequences.
+- Disposable metadata indexes live in each entity folder's `.generated/`
+  directory (for example `.taskset/tasks/.generated/` and
+  `.taskset/research/.generated/`), not a global `.taskset/generated/` tree.
+- Repository sync is the maintenance entrypoint: ensure canonical `.taskset/`
+  directories, migrate task and document IDs to immutable short hex IDs,
+  normalize `{sequence}-{slug}-{id}.md` filenames, repair duplicate sequence
+  prefixes by `createdAt`, rewrite repository text references atomically,
+  refresh data `.gitignore` rules for scoped generated output, remove legacy
+  global generated directories, then rebuild disposable generated views.
+- The nearest `.taskset/` directory marks the repository root. Optional
+  `taskset.config.ts` at that root configures validated project metadata and
+  task creation defaults. Missing config uses built-in defaults. Config never
+  relocates canonical `.taskset/` data or becomes a second task store.
+- Taskset is developed using its own `.taskset/` data, optional root config,
+  CLI, and canonical task files. Keep that dogfooding workflow operational when
+  changing core, CLI, workspace commands, or persisted contracts.
+- Public docs split three audiences: humans (`docs/`), agents (`docs/agents/`
+  plus `skills/` and root `AGENTS.md`), and maintainers (`docs/maintainers/`).
+
+## Organize by Ownership
+
+Use the architecture appropriate to the owning surface:
+
+- Use feature-based architecture for UI and interface packages such as Kanban,
+  Office, extension, TUI, and CLI.
+- Use a small DDD-style modular monolith for `@taskset/core` and any future
+  server runtime. Organize by domain module first, then separate domain,
+  application, and infrastructure layers within a module only when each layer
+  contains at least one type, function, or class that is not a direct
+  delegation to another layer and that has independent test coverage.
+- Keep domain modules in one deployable codebase until independent deployment
+  is justified. Do not introduce microservices, message brokers, or distributed
+  persistence for organizational aesthetics.
+- Colocate feature or module behavior, adapters, tests, and fixtures.
+- Keep a `README.md` in every package and app that states its ownership and
+  current contents.
+- Keep public usage guidance in `README.md` and `docs/`; keep repository
+  architecture and engineering guidance in `docs/maintainers/`.
+- Keep canonical website blog posts in `apps/www/posts/`; do not duplicate them
+  in `docs/`.
+- Promote code to a shared package only when two or more distinct packages
+  require the same logic and that logic has a defined, versioned interface that
+  is not expected to change with each consuming feature's evolution.
+- Keep client-specific state and presentation in the client. Keep shared domain
+  rules in core.
+
+Read [conventions.md](references/conventions.md), then the task-relevant
+conventions topic file, before adding or renaming source files, packages,
+exports, public types, entity fields, commands, or scripts.
+
+## Execute Safely
+
+1. [always] Before editing:
+   - Run `git status --short --branch`.
+   - Identify user-owned changes and work with them.
+   - Search for existing contracts, helpers, schemas, commands, and tests.
+   - Determine whether each target is owned source, canonical Taskset data,
+     generated output, or cache.
+   - Read [workflows.md](references/workflows.md), then the task-relevant
+     workflow topic file, for current commands and validation.
+2. [always] While editing:
+   - Keep changes in the owning layer and update required dependents.
+   - Use `workspace:*` for internal dependencies.
+   - Declare each imported dependency in the importing package manifest.
+   - Consume workspace code through package exports, never sibling `src/`
+     paths.
+   - Do not use TypeScript `paths` to bypass package boundaries.
+   - Do not hand-edit generated output or caches.
+   - Use structured YAML and Markdown parsers for entity files.
+   - Keep serialization deterministic and filesystem writes failure-safe.
+   - Prefer test-first work for domain rules, bug fixes, parsers, migrations,
+     and lifecycle transitions. During exploratory spikes, defer tests until
+     the approach stabilizes, then add the minimum focused tests before the
+     change is complete.
+   - Add the minimum number of focused tests that assert the specified behavior
+     and cover task-specific edge cases such as malformed input, boundary
+     values, and failure paths where applicable. Do not add tests for
+     implementation details or untested assumptions.
+3. [always] Verify by risk:
+   - Run the narrowest useful check first, then broaden.
+   - Focused unit or fixture test.
+   - Owning package test and type/build check.
+   - Root Biome check and relevant Turbo tasks.
+   - Cross-package integration test.
+   - CLI, MCP, filesystem, or UI workflow test when behavior crosses those
+     boundaries.
+   - For persisted data behavior, include malformed input, round-trip
+     stability, path normalization, graph integrity, and interrupted-write
+     cases as relevant.
+   - Never claim a check passed unless it ran successfully.
+4. [always] Before completion:
+   - Run `git diff --check` and review the scoped diff.
+   - Confirm canonical `.taskset/` files remain the only persistent authority.
+   - Confirm package dependencies point inward toward contracts, utilities,
+     and core, not sideways between clients.
+   - Update `docs/` and this skill when the change alters product behavior,
+     architecture, commands, persisted formats, or repository workflows.
+   - Add a Changeset when release policy is configured and versioned behavior
+     changed.
+   - If release policy configuration is absent or ambiguous, report the gap
+     and do not add a Changeset. If it is unclear whether a behavior change is
+     versioned, default to adding a Changeset with a patch bump and note the
+     uncertainty in the Changeset summary.
+   - Do not add a Changeset for skill-only, test-only, formatting-only, or
+     internal documentation changes.
+   - Report behavior, affected boundaries, checks run, and pre-existing
+     failures.
+
+Read [release.md](references/release.md) for compatibility and definition of
+done.

package/skills/taskset-implement/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Taskset Standards"
+  short_description: "Apply Taskset architecture and workflow rules"
+  default_prompt: "Use $taskset-implement to apply Taskset storage, modular architecture, naming, testing, documentation, and release conventions to this change."

package/skills/taskset-implement/references/architecture/client-and-server.md

@@ -0,0 +1,69 @@
+# Client And Server Architecture
+
+Feature-based clients and the DDD-lite modular monolith for core and server code.
+
+## Client and Server Architecture
+
+### Feature-based clients
+
+Apply FBA to presentation and interaction surfaces: Kanban, Office, extension,
+TUI, CLI, and the documentation website.
+
+Example feature roots:
+
+```text
+src/
+├── tasks/
+├── search/
+├── graph/
+├── projects/
+├── context/
+└── shared/
+```
+
+Guidelines:
+
+- Colocate feature implementation, tests, fixtures, and presentation.
+- Keep package entrypoints thin.
+- Use `shared/` only for code genuinely shared by several features in that
+  package.
+- Promote behavior to `contracts`, `utils`, or `core` only when its ownership
+  matches that package.
+- Avoid generic catch-all modules such as a growing `helpers.ts`.
+- Keep board state in Kanban, editor state in the extension, terminal state in
+  TUI, and stakeholder presentation in Office.
+
+### DDD-lite modular monolith
+
+Use a modular monolith for core and future server-side code. Organize by domain
+module before technical layer:
+
+```text
+src/
+├── tasks/
+│   ├── domain/
+│   ├── application/
+│   └── infrastructure/
+├── graph/
+├── projects/
+├── search/
+└── repository/
+```
+
+Keep this deliberately small:
+
+- `domain/` contains entities, value objects, invariants, and pure policies.
+- `application/` contains use cases and ports that coordinate domain behavior.
+- `infrastructure/` contains filesystem, Git, process, network, and framework
+  adapters.
+- Omit a layer when a module does not need it.
+- Communicate between modules through explicit public APIs, not internal file
+  imports.
+- Keep one process and one deployable unit until scale or isolation provides a
+  measured reason to split it.
+
+`@taskset/core` is the reusable modular domain engine. If remote Office or
+hosted collaboration later requires a server, introduce `apps/server/` as a
+thin composition root over core. The server owns transport, authentication,
+authorization, repository checkout, concurrency, and process lifecycle. It
+does not become a second implementation of Taskset rules.

package/skills/taskset-implement/references/architecture/documentation-and-generated.md

@@ -0,0 +1,72 @@
+# Documentation And Generated Sources
+
+Documentation architecture, interface boundaries, integrations, and generated sources.
+
+## Documentation Architecture
+
+`docs/` is the canonical source for documentation. Its top-level pages contain
+user-facing product guidance. `docs/maintainers/` owns product direction,
+architecture, ADRs, engineering workflows, and technology policy. Keep the
+maintainer section visibly separate from the primary usage flow.
+
+`apps/www/` renders `docs/` through Nextra. Its `content` symlink points to the
+root `docs/` directory so the app does not maintain a copied documentation
+tree. Top-level usage docs and `docs/maintainers/` use separate route layouts
+and page maps so their navigation stays audience-specific. Chronological
+release and project posts are a separate website-owned content type stored
+canonically in `apps/www/posts/`.
+
+Use plain Markdown by default. Use MDX only when a page needs an interactive
+component. Keep frontmatter compatible with the documentation renderer.
+
+Recommended website stack:
+
+- Next.js App Router because the repository already carries a Next.js shared
+  configuration and `apps/www` also owns marketing pages
+- Nextra with the stock docs and blog themes
+- Nextra's standard content-directory catch-all route
+- route-isolated docs and blog layouts with separate MDX component sets
+- self-hosted search initially; no CMS or remote content database
+
+Register blog posts in the app-local post registry so static export can
+enumerate `/posts/[slug]`. Keep blog posts in plain Markdown by default with
+`title`, `description`, and `date` frontmatter. Do not merge docs and blog theme
+wrappers in the global MDX component map. Agent operating pages live under
+`docs/agents/` and appear in usage navigation; maintainer pages stay under
+`/maintainers`.
+
+Keep architectural decisions under
+`docs/maintainers/architecture/decisions/`.
+Update user docs, maintainer docs, tests, and this standards skill together
+when their contracts change.
+
+## Interfaces and Integrations
+
+- CLI commands are scriptable: stable exit codes, useful stdout, diagnostics on
+  stderr, and structured output when supported.
+- MCP tools expose the same validated operations as CLI and other clients. MCP
+  must not bypass filesystem, graph, or lifecycle rules.
+- TUI, Kanban, extension, and Office are projections over core state, not
+  independent stores.
+- Office needs an explicit repository, branch, authentication, refresh, and
+  write-concurrency model before it performs remote mutations.
+- Integration packages use explicit import, export, or synchronization
+  contracts. Conflicts and ownership direction must be visible.
+- GitHub, Jira, Linear, ClickUp, and Notion are integrations, not implicit
+  authorities.
+
+## Generated Sources
+
+Treat these as generated or ephemeral unless an owning tool says otherwise:
+
+- `node_modules/`
+- `dist/`, `build/`, `out/`, `.next/`
+- `.turbo/`, coverage, logs, and `*.tsbuildinfo`
+- `.taskset/tasks/.generated/` and each document-kind `.generated/` directory
+- `.taskset/cache/`
+- `.taskset/snapshots/`
+- Nextra and Next.js generated website output
+- legacy `.taskset/generated/` (removed by `generate` / `sync`)
+
+Change the source or generator, then regenerate. Never make a manual output edit
+the final implementation.