@pennixrv/trellis 0.7.0-beta.9 → 0.7.1

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 |

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

@@ -1,75 +1,34 @@
 # Local Workflow System
 
-`.trellis/workflow.md` is the Trellis workflow source of truth inside the user project. An AI does not need Trellis source code to understand how the current project should move tasks forward; this file is enough.
+The installed project's .trellis/workflow.md is the local workflow source. Read it before changing task guidance or platform entry points.
 
-## File Responsibilities
+## Business phases
 
-`.trellis/workflow.md` has three responsibilities:
+The workflow keeps its business phases distinct, with separate activities, outputs, and transition conditions:
 
-1. **Explain workflow phases**: Plan, Execute, Finish.
-2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
-3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
+- 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
 
-## Current Phase Model
+The task route may skip a phase when evidence shows it adds no value. 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. During Delivery Review and On-Site Closeout Phase, review the current delivery and handle task completion or cancellation.
 
-```text
-Phase 1: Plan    -> clarify what to build, produce prd.md and required research
-Phase 2: Execute -> implement against the PRD and specs, then check
-Phase 3: Finish  -> final verification, preserve lessons, and wrap up
-```
+Phase identifiers, route revisions, accepted artifact revisions, and authorization are stored and changed through Trellis CLI. Skills and Hooks guide or surface the active phase; they do not create another state source. Formal session handoff is independent of the task and its phases.
 
-Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
+## Skill routing and state prompts
 
-## Skill Routing
+Each phase Skill owns its procedure and diagram. The workflow entry routes to the Skill matching the current phase identifier. Component Skills are selected by the work required, not by a fixed phase checklist.
 
-`workflow.md` separates routing by platform capability:
+Workflow-state blocks provide per-turn breadcrumbs. Keep their phase identifiers aligned with Core and update host parsers when headings or state tags change. Do not derive a phase from task status or artifact presence when Trellis CLI provides the current route.
 
-- Platforms with sub-agent support: dispatch `trellis-implement` by default for implementation and `trellis-check` for checking.
-- Platforms without sub-agent support: the main session reads skills such as `trellis-before-dev`, then executes directly.
-
-When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
-
-## Workflow-State Prompt Blocks
-
-The bottom of `workflow.md` can contain state blocks like this:
-
-```text
-[workflow-state:no_task]
-...
-[/workflow-state:no_task]
-```
-
-Hooks choose the right block based on current task status and inject it into the conversation. Common states include:
-
-| State | Meaning |
-| --- | --- |
-| `no_task` | The current session has no active task. |
-| `planning` | The task is still in requirements, research, or context configuration. |
-| `in_progress` | The task has entered implementation and checking. |
-| `completed` | The task is complete and waiting for wrap-up or archive. |
-
-If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
-
-## Local Modification Patterns
-
-Common changes:
+## Local modification patterns
 
 | Goal | Edit point |
 | --- | --- |
-| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
-| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
-| Change the default implementation/check path | Update Phase 2 and skill routing. |
-| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
-| Change platform differences | Update routing descriptions grouped by platform. |
-
-After editing, make the AI reread `.trellis/workflow.md`; do not assume the flow from the old conversation is still valid.
-
-## Relationship To Platform Files
-
-`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
-
-- skills, such as `trellis-brainstorm` and `trellis-check`.
-- commands/prompts/workflows, such as continue and finish-work.
-- hooks, such as session-start or workflow-state injection.
+| Change phase activities or transitions | .trellis/workflow.md and the matching phase Skill |
+| Change component routing | .trellis/workflow.md and pennix-workflow-routing where applicable |
+| Change lifecycle or phase state | Trellis CLI task workflow implementation and its contract |
+| Change platform context injection | Relevant Hook or plugin, keeping the Trellis task record authoritative |
 
-If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.
+After a shared workflow change, inspect relevant platform entry files for stale behavior. Keep phase-specific workflows distinct.

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/skills-and-commands.md

@@ -11,7 +11,7 @@ Skills and commands are textual entry points for user interaction with Trellis.
 | prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
 | workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
 
-Trellis workflow skills usually share one semantic set: brainstorm, before-dev, check, update-spec, break-loop. Multi-file built-in skills such as `trellis-meta` use layered references.
+Trellis skills can cover reusable capabilities or dedicated workflow areas. Multi-file bundled skills such as `trellis-meta` keep supporting material in layered references.
 
 ## Common Paths
 

package/dist/templates/common/bundled-skills/trellis-session-insight/SKILL.md

@@ -68,7 +68,7 @@ trellis mem list --cwd <project-path>
 trellis mem projects   # → list active project cwds, then narrow
 ```
 
-Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create`/`replan` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
 
 ## Triggering patterns
 

package/dist/templates/common/bundled-skills/trellis-session-insight/references/cli-quick-reference.md

@@ -23,7 +23,7 @@ Full flag reference for the five subcommands. Pin this as the authoritative sour
 | `--cwd <path>`                                | list / search     | Force a specific project cwd instead of inferring from where you are.                                                                                      |
 | `--limit N`                                   | list / search     | Cap output rows. Default `50`.                                                                                                                             |
 | `--grep KW`                                   | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated.                                                                                        |
-| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create/replan, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
+| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
 | `--turns N`                                   | context           | Number of hit turns to return. Default `3`.                                                                                                                |
 | `--around N`                                  | context           | Surrounding turns to include per hit. Default `1`.                                                                                                         |
 | `--max-chars N`                               | context           | Total character budget. Default `6000` (~1500 tokens).                                                                                                     |

package/dist/templates/common/bundled-skills/trellis-solution-design-and-convergence/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: trellis-solution-design-and-convergence
+description: 当前任务处于解决方案设计与收敛阶段时，处理用户决定、方案完整性、外部先例和实施合同。
+---
+
+# 解决方案设计与收敛阶段
+
+当 `current_phase_id` 为 `solution_design_and_convergence` 时使用。阅读本 Skill 同目录的 `workflow.md`，核对当前有效的需求基线和决策空间构造与归并阶段结果或跳过记录。
+
+本阶段锁定当前路线所依据的决定和方案，不代表实施已获授权。需用户决定时，使用 `pennix-decision-grill` 同步询问并留在解决方案设计与收敛阶段；实施路线须形成 `implementation_contract`，再单独取得实施批准后才能进入任务实施与测试验证阶段。触发 prior-art review 的方案须在阶段结果接受前完成该审查。