@pennixrv/trellis 0.7.0-beta.8 → 0.7.1-beta.0

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-task-lifecycle.md

@@ -1,91 +1,43 @@
 # Change Local Task Lifecycle
 
-Task lifecycle includes creation, start, context configuration, finish, archive, parent/child tasks, and lifecycle hooks. The default customization targets are `.trellis/tasks/`, `.trellis/config.yaml`, and `.trellis/scripts/`.
+Read the installed project's workflow and task record before changing task creation or lifecycle behavior. Task records remain in .trellis/tasks/ after completion or cancellation; Trellis does not archive task records.
 
-## Read These Files First
+## Read these files first
 
-1. `.trellis/workflow.md`
-2. `.trellis/config.yaml`
-3. `.trellis/scripts/task.py`
-4. `.trellis/scripts/common/task_store.py`
-5. `.trellis/scripts/common/task_utils.py`
-6. The current task's `.trellis/tasks/<task>/task.json`
+1. .trellis/workflow.md
+2. .trellis/config.yaml
+3. .trellis/scripts/task.py
+4. .trellis/scripts/common/task_store.py
+5. .trellis/scripts/common/task_workflow.py
+6. The current task's task.json
 
-## Common Needs And Edit Points
+## Common edit points
 
 | Need | Edit point |
 | --- | --- |
-| Automatically sync an external system after task creation | `hooks.after_create` in `.trellis/config.yaml`. |
-| Automatically update status after task start | `hooks.after_start` in `.trellis/config.yaml`. |
-| Return an in-progress task to planning | `hooks.after_replan` in `.trellis/config.yaml`. |
-| Run a script after task finish | `hooks.after_finish` in `.trellis/config.yaml`. |
-| Clean external resources after archive | `hooks.after_archive` in `.trellis/config.yaml`. |
-| Change default task fields | `.trellis/scripts/common/task_store.py`. |
-| Change task parsing/search | `.trellis/scripts/common/task_utils.py`. |
-| Change active task behavior | `.trellis/scripts/common/active_task.py`. |
+| Run a script after task creation or start | hooks.after_create or hooks.after_start in .trellis/config.yaml |
+| Run a script after clearing the session task pointer | hooks.after_finish in .trellis/config.yaml |
+| Change default task fields | .trellis/scripts/common/task_store.py |
+| Change task parsing or lookup | .trellis/scripts/common/task_utils.py |
+| Change lifecycle and phase contracts | .trellis/scripts/common/task_workflow.py and Core task model |
+| Change active task behavior | .trellis/scripts/common/active_task.py and host integration |
 
-## lifecycle hooks
+Lifecycle hooks receive TASK_JSON_PATH for the affected task. Hook failures should follow the existing behavior of the native operation and must not silently corrupt task state.
 
-`.trellis/config.yaml` supports:
+Keep project-specific fields under task.json meta unless the standard schema must change. When changing the schema, inspect every reader and writer.
 
-```yaml
-hooks:
-  after_create:
-    - "python3 .trellis/scripts/hooks/my_sync.py create"
-  after_start:
-    - "python3 .trellis/scripts/hooks/my_sync.py start"
-  after_finish:
-    - "python3 .trellis/scripts/hooks/my_sync.py finish"
-  after_archive:
-    - "python3 .trellis/scripts/hooks/my_sync.py archive"
-```
+## Active task behavior
 
-Hook commands receive the `TASK_JSON_PATH` environment variable, pointing to the current task's `task.json`. Hook failures should usually warn, but not block the main task operation.
+The active task pointer is scoped to an AI session under .trellis/.runtime/sessions/. Use task.py current to inspect it, task.py start to attach a task to the current session, and task.py finish to clear that session pointer. Do not introduce a shared global pointer.
 
-## Change Task Fields
+When task.py create runs inside a session with a recognized session identity, it attaches the new task to that session. Outside such a session, the task is still created but no pointer is changed; task.py start can attach it later.
 
-If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields.
+## Modification steps
 
-Example:
+1. Confirm the active task through task.py current --source.
+2. Inspect its task.json and phase state.
+3. Read the applicable Trellis specs.
+4. Change the native script or configuration that owns the behavior.
+5. Synchronize .trellis/workflow.md and affected host integrations.
 
-```json
-"meta": {
-  "linearIssue": "ENG-123",
-  "risk": "high"
-}
-```
-
-If standard fields really need to change, inspect every local script that reads `task.json`.
-
-## Change Active Task
-
-Active task is session-level state stored in `.trellis/.runtime/sessions/`. Do not fall back to a global `.current-task` model. If the user wants to change active task behavior, edit:
-
-- `.trellis/scripts/common/active_task.py`
-- platform hooks or shell session bridges
-- active task descriptions in `.trellis/workflow.md`
-
-### `task.py create` Sets the Active Pointer
-
-`cmd_create` in `.trellis/scripts/common/task_store.py` calls `set_active_task` best-effort right after writing the new task directory. The behavior:
-
-- When the calling shell carries session identity (`TRELLIS_CONTEXT_ID` env var, or any platform-specific session env that `resolve_context_key` recognizes — see `active_task.py:_ENV_SESSION_KEYS`), the per-session pointer at `.trellis/.runtime/sessions/<context_key>.json` is rewritten to point at the new task. The task's `status=planning` and `[workflow-state:planning]` fires on the very next `UserPromptSubmit`.
-- When session identity is unavailable (raw CLI invocation outside an AI session, or a platform that doesn't propagate identity to shell), the task directory is still created and `status=planning` is still written, but the active pointer is left untouched. The user can attach the task later with `task.py start <dir>` once they're back in an AI session.
-
-This makes `[workflow-state:planning]` the live breadcrumb during the brainstorm and JSONL curation work that follows `task.py create`. The pre-R7 behavior left the breadcrumb stuck on `no_task` until `task.py start`, so the planning block was effectively dead text.
-
-If you fork `task.py` to add a new creation path (e.g. an external import that bypasses `cmd_create`), audit whether your path also calls `set_active_task`. Without that call, your created tasks will not surface as active. The full status writer table is in `.trellis/spec/cli/backend/workflow-state-contract.md`.
-
-## Modification Steps
-
-1. Confirm the current task with `python3 ./.trellis/scripts/task.py current --source`.
-2. Read the current task's `task.json` and confirm status and fields.
-3. For configuration needs, edit `.trellis/config.yaml` first.
-4. For script behavior needs, then edit `.trellis/scripts/`.
-5. If the AI flow changed, synchronize `.trellis/workflow.md`.
-
-## Do Not
-
-- Do not directly edit `.trellis/.runtime/sessions/` to "fix" business state.
-- Do not hard-code project-private fields into scripts; prefer `meta`.
-- Do not default to asking the user to fork Trellis CLI.
+Do not hand-edit runtime pointers or phase state. Do not change task lifecycle outside the Trellis CLI contract.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-workflow.md

@@ -1,65 +1,26 @@
 # Change Local Workflow
 
-When the user wants to change Trellis phases, next-action hints, whether to create tasks, whether to use sub-agents, or when to check/wrap up, edit `.trellis/workflow.md` first.
+Read the installed project's .trellis/workflow.md before changing phase activities, route guidance, or platform entry points.
 
-## Read These Files First
+## Business phases
 
-1. `.trellis/workflow.md`
-2. Entry files for the current platform, such as skills/commands/prompts/workflows
-3. The current task's `task.json` and `prd.md`
+- Goal Exploration and Requirements Confirmation Phase
+- Decision Space Construction and Consolidation Phase
+- Solution Design and Convergence Phase
+- Task Implementation and Test Verification Phase
+- Delivery Review and On-Site Closeout Phase
 
-## Common Needs And Edit Points
+Each phase has its own Skill and workflow diagram. Keep their activities distinct. Trellis CLI owns task lifecycle and phase state; do not encode a second route in a Skill, Hook, or command.
 
-| Need | Edit point |
-| --- | --- |
-| Change phase names or phase order | `Phase Index` and the corresponding Phase sections. |
-| Change whether to create a task when there is no task | `[workflow-state:no_task]` state block. |
-| Change the next step during planning | Phase 1 and `[workflow-state:planning]`. |
-| Change whether an agent is required during in_progress | Phase 2 and `[workflow-state:in_progress]`. |
-| Change wrap-up after completion | Phase 3 and `[workflow-state:completed]`. |
-| Change which skill a user intent triggers | `Skill Routing` table. |
-
-## Modification Steps
-
-1. Find the relevant section in `.trellis/workflow.md`.
-2. When changing rules, keep explicit trigger conditions and next actions.
-3. If adding or renaming a skill/agent, synchronize the corresponding files in platform directories.
-4. Workflow-state changes only need an edit to the `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The hook is parser-only — it reads whatever you put in the block. Keep the opening and closing tags' STATUS strings identical (`[workflow-state:foo]…[/workflow-state:foo]`); mismatched STATUS pairs are silently dropped.
-5. Make the AI reread `.trellis/workflow.md`; do not keep using rules from the old conversation.
-
-## Example: Relax Task Creation Requirements
-
-To change when task creation can be skipped, usually edit `[workflow-state:no_task]`:
-
-```md
-[workflow-state:no_task]
-Task is not required when the answer is a one-reply explanation, no files are changed, and no research is needed.
-[/workflow-state:no_task]
-```
-
-If the formal Phase 1 flow also needs to change, synchronize the Phase 1 section.
+The Goal Exploration and Requirements Confirmation Phase requires explicit user confirmation of the current requirements revision before the route enters Decision Space Construction and Consolidation Phase or Solution Design and Convergence Phase. Acceptance in Solution Design and Convergence Phase does not grant implementation authorization. Task Implementation and Test Verification Phase follows the authorized contract. During Delivery Review and On-Site Closeout Phase, review the current delivery and handle task completion or cancellation. Routes may skip phases when the task record contains sufficient reason and evidence.
 
-## Example: One Platform Does Not Use Sub-Agents
+## Change workflow assets
 
-If the user wants only one platform to avoid sub-agents, first confirm whether that platform has a separate group in the workflow. Then change Phase 2 routing for that platform group instead of deleting all `trellis-implement` / `trellis-check` instructions across platforms.
-
-## `/trellis:continue` Route Table
-
-`/trellis:continue` resumes a task by deciding which phase step to load next. The decision combines `task.json.status` with the presence of artifacts inside the task directory. The mapping is fixed in the command itself; forks that add custom statuses must extend both the workflow.md tag block and this table.
-
-| `status` | Artifact state | Resume at |
-| --- | --- | --- |
-| `planning` | `prd.md` missing | Phase 1.1 (load `trellis-brainstorm`) |
-| `planning` | lightweight task with `prd.md` complete | ask for start review, then run `task.py start` |
-| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
-| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | ask for start review, then run `task.py start` |
-| `in_progress` | no implementation in conversation history | Phase 2.1 (`trellis-implement`) |
-| `in_progress` | implementation done, no `trellis-check` run | Phase 2.2 (`trellis-check`) |
-| `in_progress` | check passed | Phase 3.3 (spec update) → 3.4 (commit) |
-| `completed` | task is still in active tree | Phase 3.5 (run `/trellis:finish-work` to archive) |
-
-When you add a custom status (e.g. `in-review`), add a `[workflow-state:in-review]` block in `.trellis/workflow.md` for the per-turn breadcrumb AND extend this route table — usually by editing the `/trellis:continue` command file (`.{platform}/commands/trellis/continue.md` or equivalent) to add a row that decides where to resume from. Without the route entry, `/trellis:continue` will fall through to a default branch and the user will not land on the step you intended.
-
-## Notes
+| Goal | Edit point |
+| --- | --- |
+| Change phase activities or transitions | .trellis/workflow.md and the matching phase Skill |
+| Change cross-component routing | .trellis/workflow.md and pennix-workflow-routing |
+| Change phase status or acceptance | Trellis CLI task workflow contract and tests |
+| Change host context injection | Relevant Hook or plugin |
 
-`.trellis/workflow.md` is the local project workflow, not an immutable template. The user can adapt it to team habits. After editing it, platform entry files may still contain old descriptions, so inspect them too.
+Keep workflow-state phase identifiers aligned with Core and the current task record. Hooks surface state; they do not authorize or accept work. After a shared change, inspect host commands and prompts for stale instructions.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/overview.md

@@ -7,7 +7,7 @@ This directory is for local AI working in a user project where Trellis was insta
 | User wording | Read first |
 | --- | --- |
 | "Change the Trellis flow / phases / next prompt" | `change-workflow.md` |
-| "Change task creation, status, archive, or hooks" | `change-task-lifecycle.md` |
+| "Change task creation, lifecycle, phase state, or hooks" | `change-task-lifecycle.md` |
 | "AI did not read context / change injected content" | `change-context-loading.md` |
 | "A platform hook is not behaving as expected" | `change-hooks.md` |
 | "Change implement/check/research agent behavior" | `change-agents.md` |

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/bundled-skills.md

@@ -1,34 +1,38 @@
 # Bundled Skills
 
-"Bundled skills" are multi-file built-in skills shipped inside the Trellis CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into every supported platform's skill root by `trellis init` and kept in sync by `trellis update`. They are part of Trellis itself, not third-party content.
+"Bundled skills" are Trellis CLI-owned skills shipped inside the CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into supported platform skill roots by `trellis init` and managed by `trellis update`. They are part of Trellis itself, not third-party content.
 
-A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that already contains its own `SKILL.md` (with YAML frontmatter) plus optional `references/`, assets, or other supporting files. Trellis copies the whole directory tree as-is into each platform's skill root, so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
+A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that contains its own `SKILL.md` (with YAML frontmatter) and may include `references/`, assets, or other supporting files. Trellis copies the complete directory tree into each platform's skill root, resolving supported placeholders per platform so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
 
 ## What Counts As Bundled (vs. Adjacent Concepts)
 
 | Source path | Type | How it ships |
-| --- | --- | --- |
+| --------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `templates/common/bundled-skills/<name>/` | Bundled skill (multi-file) | Whole directory copied to every platform skill root |
 | `templates/common/skills/<name>.md` | Single-file workflow skill | Wrapped with frontmatter, written as `<root>/<name>/SKILL.md` |
 | `templates/common/commands/<name>.md` | Slash command / prompt | Written to each platform's command directory (`.claude/commands/trellis/`, `.cursor/commands/trellis-*.md`, `.gemini/commands/trellis/*.toml`, etc.) |
 | `templates/<platform>/skills/` | Platform-specific skill | Written only into that platform's directory (e.g. `.codex/skills/`) |
 | User skills under `.claude/skills/<my-skill>/` etc. | Marketplace or user-authored | Not managed by Trellis at all |
 
-The Trellis CLI never touches anything that is not produced by one of its own template loaders. Anything a user drops into a platform skill root by hand is left alone.
+Only paths emitted by Trellis template loaders are managed by Trellis. Other files in a platform skill root are outside those write paths.
 
 ## Current Bundled Skills
 
 The set is discovered at runtime by listing directories under `templates/common/bundled-skills/`:
 
 | Skill | Purpose |
-| --- | --- |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trellis-goal-exploration-and-requirements` | Clarifies a task's goal, scope, success conditions, constraints, evidence, and user confirmation. |
+| `trellis-decision-space-construction-and-merging` | Organizes substantive decisions, options, evidence, dependencies, and decision trees. |
+| `trellis-solution-design-and-convergence` | Resolves user decisions, plan completeness, external precedents, and the implementation contract. |
+| `trellis-task-implementation` | Advances the authorized implementation contract through work packages, verification, integration, and blocker handling. |
+| `trellis-delivery-review-and-closeout` | Reviews the delivery candidate, unresolved items, acceptance conditions, and resource disposition. |
 | `trellis-meta` | This skill. Explains the local Trellis architecture and customization entry points to an AI working inside a user project. |
 | `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex / Pi Agent conversation logs. |
 | `trellis-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.trellis/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
-| `trellis-channel` | Capability skill teaching an AI when to reach for `trellis channel` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
-| `trellis-research-record` | Records verified research, audit, or review findings in the active task without creating a second task ledger. |
+| `trellis-teamwork`        | Capability skill teaching an AI when to reach for `trellis teamwork` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
 
-The list is discovered at runtime, so adding a new directory under `bundled-skills/` is the only step required to register a new skill (see "Adding a New Bundled Skill" below).
+This inventory reflects the directories currently in the source tree. The CLI discovers them at runtime, so adding a directory under `bundled-skills/` makes it available to the shared loader (see "Adding a New Bundled Skill" below).
 
 ## Where Bundled Skills Land Per Platform
 
@@ -37,7 +41,7 @@ A platform's whole file set — commands, workflow skills, agents, hooks, bundle
 All 21 platforms receive the full bundled-skill set:
 
 | Platform | Bundled skill root |
-| --- | --- |
+| ----------- | ---------------------------- |
 | Claude Code | `.claude/skills/<skill>/` |
 | Cursor | `.cursor/skills/<skill>/` |
 | OpenCode | `.opencode/skills/<skill>/` |
@@ -64,7 +68,7 @@ Codex, Gemini CLI, Pi and Kimi share the `.agents/skills/` root (the upstream Ag
 
 One description, two consumers:
 
-1. `trellis init` → `configurePlatform(platformId, cwd)` → `writeTemplateMap(cwd, collect<Platform>Templates())`. For 18 of the 21 platforms the registry entry in `configurators/index.ts` is literally `fromTemplates(collect<Platform>Templates)`, which *is* that composition. Claude Code, Codex and ZCode spell out a `configure` of their own, each for work a `Map<path, content>` cannot express (an opt-in `--with-statusline` flag, an intentionally empty `.codex/skills/` directory, a one-shot console notice) — none of them restates the file list.
+1. `trellis init` → `configurePlatform(platformId, cwd)` → `writeTemplateMap(cwd, collect<Platform>Templates())`. For 18 of the 21 platforms the registry entry in `configurators/index.ts` is literally `fromTemplates(collect<Platform>Templates)`, which _is_ that composition. Claude Code, Codex and ZCode spell out a `configure` of their own, each for work a `Map<path, content>` cannot express (an opt-in `--with-statusline` flag, an intentionally empty `.codex/skills/` directory, a one-shot console notice) — none of them restates the file list.
 2. `trellis update` → `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) → the same map, used to detect drift and to populate `.trellis/.template-hashes.json`.
 
 Because both consumers read the one description, init and update cannot disagree about which files a bundled skill produces.
@@ -115,7 +119,6 @@ The shape and dispatch wiring are already generic, so adding a skill requires on
 4. **No dispatch wiring is required.** `listDirectories("bundled-skills")` discovers the new directory automatically, so all platforms receive it on the next `trellis init` or `trellis update`.
 
 5. **Verify the distribution path** before shipping. Skipping any of these steps has historically caused features to be documented as bundled while the published npm tarball was missing the files:
-
    - Source files exist on the branch being tagged.
    - `pnpm --filter @pennixrv/trellis build` copies the asset into `dist/templates/common/bundled-skills/<skill>/`.
    - `npm pack --dry-run --json` includes the expected `dist/**` paths.

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/generated-files.md

@@ -10,7 +10,6 @@ This page only describes files that are visible and editable inside the user pro
 .trellis/
 ├── workflow.md
 ├── config.yaml
-├── .gitignore
 ├── .developer
 ├── .version
 ├── .template-hashes.json
@@ -25,7 +24,6 @@ This page only describes files that are visible and editable inside the user pro
 | --- | --- | --- |
 | `.trellis/workflow.md` | Yes | Local workflow documentation and AI routing rules. |
 | `.trellis/config.yaml` | Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
-| `.trellis/.gitignore` | No | Generated ignore rules for local Trellis state. Track it, but do not normally edit it. |
 | `.trellis/spec/` | Yes | Project specs, intended to be updated regularly by users and AI. |
 | `.trellis/tasks/` | Yes | Task material and research artifacts, maintained by the task workflow. |
 | `.trellis/workspace/` | Yes | Session records, usually written by `add_session.py`. |
@@ -35,37 +33,6 @@ This page only describes files that are visible and editable inside the user pro
 | `.trellis/.version` | No | Trellis version record used by update/migration logic. |
 | `.trellis/.template-hashes.json` | No | Template hash record. Do not hand-write business rules here. |
 
-## Git Tracking
-
-`trellis init` and `trellis update` are the single project-asset generation
-path. Do not add a second project initializer for Trellis files or platform
-integration files: use those commands to create or refresh the generated
-assets, then review and commit the resulting project changes normally.
-
-For a Git-tracked project, commit the durable project contract:
-
-- `.trellis/workflow.md`, `config.yaml`, `scripts/`, `spec/`, `tasks/`, and
-  `workspace/`;
-- `.trellis/.version` and `.trellis/.template-hashes.json`. They are generated
-  metadata, not hand-edited configuration; keeping them lets another clone
-  distinguish Trellis-owned templates from local changes safely;
-- the Trellis-managed files in selected platform directories, plus the
-  root-level `AGENTS.md` managed block when Trellis created or merged it.
-
-Do not commit local or ephemeral state. The generated `.trellis/.gitignore`
-already excludes `.developer`, `.current-task`, `.runtime/`, `.ralph-state.json`,
-agent runtime files, atomic-update files, backups, and Python caches. Platform
-session history, caches, logs, and credentials are platform-owned rather than
-Trellis templates; apply the platform's own ignore rules or the repository's
-security policy to them. If workspace journals contain data that the project
-policy forbids in Git, add a project-specific ignore rule rather than changing
-the shared Trellis template for every project.
-
-Generated does not mean disposable: `workflow.md`, specs, tasks, journals, and
-the template-hash receipt are ordinary project artifacts. Conversely, Trellis
-does not infer or broadly ignore all platform directories because doing so
-would hide user-owned files that it must preserve.
-
 ## Platform Directories
 
 Different platforms generate different directories. Common categories:

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/multi-agent-teamwork.md

@@ -0,0 +1,32 @@
+# Teamwork Runtime
+
+`trellis teamwork` provides durable coordination sessions and teammate processes. Its session lifecycle is independent of the Trellis task lifecycle and phase route. A session may be associated with a task, but it never owns task status, phase state, or phase acceptance.
+
+## Local surfaces
+
+| Surface | Purpose |
+| --- | --- |
+| `~/.trellis/teamwork/<project>/<session>/events.jsonl` | Durable Teamwork Session event log. |
+| `.trellis/agents/teammate.md` | Generic behavior card loaded for a teammate. |
+| `.trellis/agents/teammate-profiles.json` | Provider and execution profiles. |
+| `.trellis/config.yaml` (`teamwork.*`) | Teammate concurrency and process guard settings. |
+| `packages/core/src/teamwork/` | Reusable Teamwork Session event and storage APIs. |
+| `packages/cli/src/commands/teamwork/` | CLI commands, provider adapters, and process supervision. |
+
+The storage root defaults to `~/.trellis/teamwork`; `TRELLIS_TEAMWORK_ROOT` overrides it. The project bucket defaults to a key derived from the current working directory; `TRELLIS_TEAMWORK_PROJECT` overrides that key.
+
+## Ownership
+
+- Trellis Core owns reusable Teamwork Session event, storage, and coordination contracts.
+- The Trellis CLI owns command handling, teammate process supervision, and task-bound batch artifacts.
+- The active Trellis task remains the source of truth for task and phase state. Teamwork dispatch and reports may bind to its current phase and revisions; Teamwork does not write phase acceptance.
+- Accepted reports remain task evidence. Temporary batch data may be removed when the batch settles. Teamwork Session event logs follow their own lifecycle.
+- Host capabilities must pass the configured capability check before batch execution. A provider contract or fixture alone does not establish that a host is available.
+
+## Configuration
+
+The project configuration supports `teamwork.teammate.max_concurrency` and `teamwork.teammate_guard.idle_timeout`, `max_live_teammates`, and `non_batch_reserved`. Defaults and CLI overrides are defined by the current Trellis CLI; read `packages/cli/src/commands/teamwork/teammate-config.ts` before changing them.
+
+## Related entry points
+
+Use the bundled `trellis-teamwork` Skill for command usage and teammate coordination. Use `trellis workflow` and the active task record for workflow behavior. Do not route task or phase transitions through a Teamwork Session.

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/spec-system.md

@@ -95,7 +95,7 @@ When the AI learns a new rule during implementation or debugging, it should upda
 | Change monorepo spec mapping | `packages` / `default_package` / `spec_scope` in `.trellis/config.yaml`. |
 | Change which specs AI reads before implementation | The task's `implement.jsonl`. |
 | Change which specs AI reads during checking | The task's `check.jsonl`. |
-| Change when specs should be updated | Phase 3.3 in `.trellis/workflow.md` and the `trellis-update-spec` skill. |
+| Change when specs should be updated | Solution Design and Convergence Phase guidance in `.trellis/workflow.md` and the `trellis-update-spec` skill. |
 
 ## Boundaries
 

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/task-system.md

@@ -1,130 +1,44 @@
 # Local Task System
 
-The Trellis task system is stored entirely under `.trellis/tasks/` in the user project. Each task is a directory containing requirements, context, research, state, and relationship information.
-
-## Task Directory Structure
-
-```text
-.trellis/tasks/
-├── 04-28-example-task/
-│   ├── task.json
-│   ├── prd.md
-│   ├── design.md
-│   ├── implement.md
-│   ├── implement.jsonl
-│   ├── check.jsonl
-│   └── research/
-└── archive/
-    └── 2026-04/
-```
-
-| File | Purpose |
-| --- | --- |
-| `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
-| `prd.md` | Requirements, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
-| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
-| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
-| `implement.jsonl` | List of spec/research files the implement agent must read first. |
-| `check.jsonl` | List of spec/research files the check agent must read first. |
-| `research/` | Research artifacts. Complex findings should not live only in chat. |
-
-## `task.json`
-
-`task.json` records task status and metadata. Common fields:
-
-| Field | Meaning |
-| --- | --- |
-| `id` / `name` / `title` | Task identity and title. |
-| `status` | Status such as `planning`, `in_progress`, `review`, or `completed`. |
-| `priority` | `P0`, `P1`, `P2`, `P3`. |
-| `creator` / `assignee` | Creator and assignee. |
-| `package` | Target package in a monorepo; may be empty. |
-| `branch` / `base_branch` | Working branch and PR target branch. |
-| `children` / `parent` | Parent/child task relationships. |
-| `commit` / `pr_url` | Commit and PR information after completion. |
-| `meta` | Extension fields. |
-
-## Parent / Child Task Trees
-
-Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
-
-Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
-
-- Source requirements and user-facing scope.
-- The map of child tasks and their responsibility boundaries.
-- Cross-child acceptance criteria and final integration review.
+Tasks live under .trellis/tasks/. A task record keeps its artifacts and history in place after completion or cancellation; Trellis does not move tasks into an archive.
 
-Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
+## Task records
 
-Create new children with:
+Each task directory may contain task.json, prd.md, design.md, implement.md, research/, and context manifests. Use only the artifacts needed by the task.
 
-```bash
-python3 ./.trellis/scripts/task.py create "<child title>" --description "<one-line summary>" --slug <child-slug> --parent <parent-dir>
-```
+task.json records identity, lifecycle status, ownership, and parent/child relationships. The Trellis CLI task workflow record stores the ordered phase route, current phase, revisions, evidence, acceptance, and authorization. Do not edit lifecycle or phase status by hand.
 
-Link or unlink existing tasks with:
+## Parent and child tasks
 
-```bash
-python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
-python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>
-```
+A parent groups related deliverables and records cross-task acceptance. Each child has its own task record and lifecycle. Record dependencies explicitly in task artifacts; tree position does not imply execution order.
 
-`children` on the parent is a historical list. When a child is archived, Trellis keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
+## Active task context
 
-The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
+The active task pointer is scoped to an AI session under .trellis/.runtime/sessions/. Use task.py current to inspect it, task.py start to attach a task to the current session, and task.py finish to clear the current session pointer. Do not create a shared global pointer.
 
-## Active Task
+## Native task operations
 
-The user sees a "current task," but Trellis stores active task state per session.
+    python3 ./.trellis/scripts/task.py create "<title>" --description "<summary>" [--parent <task>]
+    python3 ./.trellis/scripts/task.py phase show <task>
+    python3 ./.trellis/scripts/task.py validate <task>
+    python3 ./.trellis/scripts/task.py start <task>
+    python3 ./.trellis/scripts/task.py complete <task>
+    python3 ./.trellis/scripts/task.py cancel <task> --reason "<reason>" --evidence-ref <reference>
 
-```text
-.trellis/.runtime/sessions/<context-key>.json
-```
+Use phase operations through task.py phase for artifact revisions, acceptance, evidence-backed skips, waits, blocks, resume, return, route, and authorization. Consult task.py help for current arguments. Completion and cancellation occur only after Delivery Review and On-Site Closeout Phase.
 
-`task.py start` writes the task path into the runtime session file for the current session. `task.py current --source` shows the current task and where it came from. Different AI windows can point to different tasks without overwriting each other.
+The read-only trellis task progress command summarizes planning, in_progress, and completed lifecycle records. It does not change task state.
 
-If the platform or shell environment has no stable session identity, `task.py start` may be unable to set the active task. The AI should read the error, inspect the platform hook/session environment, and not fall back to a shared global pointer.
+## Context manifests
 
-## JSONL Context
+implement.jsonl and check.jsonl identify relevant spec and research files for agents that consume those manifests. They do not replace the task's planning artifacts. Keep entries curated and remove placeholder rows rejected by task.py validate.
 
-`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
-
-Format:
-
-```jsonl
-{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend conventions"}
-{"file": ".trellis/tasks/04-28-example/research/api.md", "reason": "API research"}
-```
-
-Rules:
-
-- Include spec and research files.
-- Do not include code files that are about to be modified.
-- Do not treat temporary conclusions in chat as the only context.
-- Rows without a `file` field are skipped by readers. Legacy `{"_example": ...}` placeholder rows are rejected by `task.py validate` — delete them.
-
-## Common Commands
-
-```bash
-python3 ./.trellis/scripts/task.py create "<title>" --description "<one-line summary>" --slug <slug>
-python3 ./.trellis/scripts/task.py start <task>
-python3 ./.trellis/scripts/task.py current --source
-python3 ./.trellis/scripts/task.py add-context <task> implement <file> <reason>
-python3 ./.trellis/scripts/task.py validate <task>
-python3 ./.trellis/scripts/task.py finish
-python3 ./.trellis/scripts/task.py archive <task>
-```
-
-When modifying the task system, the AI should prefer script commands to maintain structure. Edit JSON/Markdown directly only when scripts do not cover the need.
-
-## Local Customization Points
+## Local customization points
 
 | Need | Edit location |
 | --- | --- |
-| Change the default task template | `.trellis/scripts/common/task_store.py` and task creation instructions. |
-| Change status semantics | `.trellis/workflow.md`, workflow-state hook logic, and task usage conventions. |
-| Add task lifecycle actions | `hooks.after_*` in `.trellis/config.yaml`. |
-| Change context rules | Planning artifact guidance in `.trellis/workflow.md` and related platform agent/hook instructions. |
-| Change archive policy | `.trellis/scripts/common/task_store.py` / `task_utils.py`. |
-
-These are local files in the user project. Do not default to editing Trellis CLI source code unless the user wants to contribute upstream.
+| Change task fields or creation | .trellis/scripts/common/task_store.py |
+| Change task lookup or parsing | .trellis/scripts/common/task_utils.py |
+| Change lifecycle and phase contracts | .trellis/scripts/common/task_workflow.py and Core task model |
+| Change active session task behavior | .trellis/scripts/common/active_task.py and host integration |
+| Change task guidance | .trellis/workflow.md and the applicable phase Skill |