chore: migrate from opencode to trellis 0.5.0-rc.6

- Remove legacy .opencode/ directory and configuration - Update .trellis/ to v0.5.0-rc.6 structure - Refactor scripts: modularize common/, remove multi_agent/ - Add new common modules: git.py, io.py, log.py, types.py, etc. - Update workflow.md and AGENTS.md - Archive completed migration tasks
2026-05-06 14:29:25 +08:00
parent 4e234be647
commit 04b493ed09
102 changed files with 8377 additions and 9922 deletions
@@ -0,0 +1,83 @@
+# Add Project-Local Conventions
+
+Often the user does not need to change Trellis mechanics; they need local AI to understand their team's conventions. In that case, prefer `.trellis/spec/` or a project-local skill instead of editing `trellis-meta`.
+
+## Where To Put Things
+
+| Content type | Location |
+| --- | --- |
+| Rules code must follow | `.trellis/spec/<layer>/` |
+| Cross-layer thinking methods | `.trellis/spec/guides/` |
+| AI capability for a project-specific flow | Platform-local skill |
+| One-off task material | `.trellis/tasks/<task>/` |
+| Session summary | `.trellis/workspace/<developer>/journal-N.md` |
+
+## Create A Project-Local Skill
+
+If the user wants AI to know "how this project customizes Trellis," create a local skill:
+
+```text
+.claude/skills/trellis-local/
+└── SKILL.md
+```
+
+Example:
+
+```md
+---
+name: trellis-local
+description: "Project-local Trellis customizations for this repository. Use when changing this project's Trellis workflow, hooks, local agents, or team-specific conventions."
+---
+
+# Trellis Local
+
+## Local Scope
+
+This skill documents this repository's Trellis customizations only.
+
+## Custom Workflow Rules
+
+- ...
+
+## Local Hook Changes
+
+- ...
+
+## Local Agent Changes
+
+- ...
+```
+
+For multi-platform projects, place equivalent versions in other platform skill directories, or use `.agents/skills/` for platforms that support the shared layer.
+
+## Write To `.trellis/spec/`
+
+If the content is a coding convention, write it to spec. Examples:
+
+```text
+.trellis/spec/backend/error-handling.md
+.trellis/spec/frontend/components.md
+.trellis/spec/guides/cross-platform-thinking-guide.md
+```
+
+After writing it, update the corresponding `index.md` so AI can find the new rule from the entry point.
+
+## Make The Current Task Use New Conventions
+
+After writing a spec, add it to the current task context:
+
+```bash
+python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/backend/error-handling.md" "Error handling conventions"
+python3 ./.trellis/scripts/task.py add-context <task> check ".trellis/spec/backend/error-handling.md" "Review error handling"
+```
+
+## Do Not Store Project-Private Rules In `trellis-meta`
+
+`trellis-meta` is a public skill for understanding Trellis architecture and local customization entry points. Put project-private content in:
+
+- `.trellis/spec/`
+- a project-local skill
+- the current task
+- workspace journal
+
+This prevents future updates to Trellis's built-in `trellis-meta` from overwriting the team's own conventions.
@@ -0,0 +1,54 @@
+# Change Local Agents
+
+When the user wants to change `trellis-research`, `trellis-implement`, or `trellis-check` behavior, edit platform agent files in the user project.
+
+## Read These Files First
+
+1. Target platform agent directory
+2. `.trellis/workflow.md` Phase 2 / research routing
+3. Current task `prd.md`
+4. Current task `implement.jsonl` / `check.jsonl`
+5. Relevant hook or agent prelude
+
+## Common Paths
+
+| Platform | Path |
+| --- | --- |
+| Claude Code | `.claude/agents/trellis-*.md` |
+| Cursor | `.cursor/agents/trellis-*.md` |
+| OpenCode | `.opencode/agents/trellis-*.md` |
+| Codex | `.codex/agents/trellis-*.toml` |
+| Kiro | `.kiro/agents/trellis-*.json` |
+| Gemini CLI | `.gemini/agents/trellis-*.md` |
+| Qoder | `.qoder/agents/trellis-*.md` |
+| CodeBuddy | `.codebuddy/agents/trellis-*.md` |
+| Factory Droid | `.factory/droids/trellis-*.md` |
+| Pi Agent | `.pi/agents/trellis-*.md` |
+
+Use the actual paths in the user project as authoritative.
+
+## Common Needs
+
+| Need | Which agent to edit |
+| --- | --- |
+| Research must write files, not only reply in chat | `trellis-research` |
+| Certain local specs must be read before implementation | `trellis-implement` + `implement.jsonl` configuration rules |
+| Specific commands must run during checking | `trellis-check` |
+| Agent must not modify certain directories | The corresponding agent's write boundary instructions |
+| Agent output format must be fixed | The corresponding agent's final/reporting instructions |
+
+## Modification Principles
+
+1. **Preserve role boundaries**: research investigates and persists; implement writes implementation; check reviews and fixes.
+2. **Do not hard-code project specs into agents**: long-term specs belong in `.trellis/spec/`; agents are responsible for reading them.
+3. **Make read order explicit**: active task -> PRD -> info -> JSONL -> spec/research.
+4. **Make write boundaries explicit**: which directories may be written and which may not.
+5. **Synchronize across platforms**: when the user configured multiple platforms, decide whether to change only the current platform or all platform agents.
+
+## Agent Pull Platforms
+
+If an agent file contains a prelude for "read task/context after startup," do not remove those steps when editing. Otherwise the agent will work only from chat context and bypass Trellis's core mechanism.
+
+## Hook Push Platforms
+
+If context is injected by a hook, the agent file should still retain responsibility boundaries. Do not remove PRD/spec requirements from the agent just because a hook injects context.
@@ -0,0 +1,81 @@
+# Change Local Context Loading
+
+Context loading determines when AI reads workflow, task, spec, research, workspace, and git status. Read this page when the user says "AI does not know the current task," "the agent did not read specs," or "there is too much/too little context."
+
+## Read These Files First
+
+1. `.trellis/workflow.md`
+2. `.trellis/scripts/get_context.py`
+3. `.trellis/scripts/common/session_context.py`
+4. `.trellis/scripts/common/task_context.py`
+5. `.trellis/scripts/common/active_task.py`
+6. Current platform hooks or agent files
+7. The current task's `implement.jsonl` / `check.jsonl`
+
+## Context Sources
+
+| Source | Purpose |
+| --- | --- |
+| `.trellis/workflow.md` | Workflow and next-action hints. |
+| `.trellis/tasks/<task>/prd.md` | Current task requirements. |
+| `.trellis/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
+| `.trellis/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
+| `.trellis/spec/` | Project specs. |
+| `.trellis/workspace/` | Session records. |
+| git status | Current working tree changes. |
+
+## Common Needs And Edit Points
+
+| Need | Edit point |
+| --- | --- |
+| Inject more/less information in new sessions | `session_context.py` or the platform `session-start` hook. |
+| Change hints on each user input | `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The `inject-workflow-state` hook is parser-only and reads the block verbatim. |
+| Agent did not read specs | Task JSONL, agent prelude, `inject-subagent-context` hook. |
+| Active task is lost | `active_task.py` and platform session identity propagation. |
+| Change JSONL validation rules | `task_context.py`. |
+
+## JSONL Rules
+
+`implement.jsonl` / `check.jsonl` are the key context loading interface:
+
+```jsonl
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend conventions"}
+{"file": ".trellis/tasks/04-28-x/research/api.md", "reason": "API research"}
+```
+
+Include only spec/research files. Do not put code files that will be modified into these manifests; agents read code files themselves during implementation.
+
+## Change Session Context
+
+If the user wants every new session to see more project state, edit:
+
+- `.trellis/scripts/common/session_context.py`
+- the corresponding platform `session-start` hook
+
+Context cannot grow without bound. Prefer injecting indexes and paths so the AI can read detailed files on demand.
+
+## Change Sub-Agent Context
+
+First determine which mode the platform uses:
+
+- hook push: edit the `inject-subagent-context` hook.
+- agent pull: edit the read steps in the corresponding `trellis-implement` / `trellis-check` agent file.
+
+In both modes, make sure the agent ultimately reads:
+
+1. active task
+2. `prd.md`
+3. `info.md` if present
+4. the corresponding JSONL
+5. spec/research referenced by the JSONL
+
+## Troubleshooting Order
+
+```bash
+python3 ./.trellis/scripts/task.py current --source
+python3 ./.trellis/scripts/task.py list-context <task>
+python3 ./.trellis/scripts/task.py validate <task>
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+Confirm the task and JSONL are correct before editing hooks/agents.
@@ -0,0 +1,57 @@
+# Change Local Hooks
+
+Hooks are the automation layer that connects a platform to Trellis. When the user wants to change "when context is injected," "how shell commands inherit a session," or "which files are read before an agent starts," hooks are usually the edit point.
+
+## Read These Files First
+
+1. Target platform settings/config, such as `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`
+2. Target platform hooks directory
+3. `.trellis/scripts/common/active_task.py`
+4. `.trellis/scripts/common/session_context.py`
+5. `.trellis/workflow.md`
+
+## Common Hook Types
+
+| Hook | Purpose |
+| --- | --- |
+| session-start | Injects a Trellis overview when a session starts, clears, or compacts. |
+| workflow-state | Injects a state hint on each user input. |
+| sub-agent context | Injects PRD/spec/research before an agent starts. |
+| shell session bridge | Lets `task.py` commands in shell see the same session identity. |
+
+## Modification Steps
+
+1. Find the hook registration in settings/config.
+2. Confirm the registered script path exists.
+3. Read the hook script and identify inputs, outputs, and called `.trellis/scripts/`.
+4. Modify hook behavior.
+5. If the hook depends on workflow content, synchronize `.trellis/workflow.md`.
+
+## Example: Change New-Session Injection Content
+
+First find the session-start hook:
+
+```text
+.claude/settings.json
+.claude/hooks/session-start.py
+```
+
+If the hook ultimately calls `.trellis/scripts/get_context.py` or `session_context.py`, editing the local script is usually more robust than hard-coding content in the hook.
+
+## Example: Agent Did Not Read JSONL
+
+First confirm:
+
+```bash
+python3 ./.trellis/scripts/task.py current --source
+python3 ./.trellis/scripts/task.py validate <task>
+```
+
+If the task and JSONL are correct, determine whether the platform uses hook push or agent pull. For hook push, edit `inject-subagent-context`; for agent pull, edit the agent file.
+
+## Notes
+
+- Settings handle registration, hook scripts handle behavior; inspect both together.
+- Different platforms support different hook events. Do not directly copy another platform's settings.
+- Hooks should read project-local `.trellis/`; they should not depend on Trellis upstream source paths.
+- Hook failures should produce visible errors so AI does not silently lose context.
@@ -0,0 +1,78 @@
+# Change Local Skills, Commands, Prompts, And Workflows
+
+When the user wants to change AI entry points, auto-trigger rules, or explicit command behavior, edit skills, commands, prompts, or workflows in local platform directories.
+
+## Read These Files First
+
+1. `.trellis/workflow.md`
+2. Target platform skill/command/prompt/workflow directory
+3. Related agent or hook files
+4. Whether project rules already exist in `.trellis/spec/`
+
+## Which Entry Type To Choose
+
+| Goal | Recommendation |
+| --- | --- |
+| AI should automatically know a capability | Add or modify a skill. |
+| User wants to trigger manually with a command | Add or modify a command/prompt/workflow. |
+| Team project conventions | Prefer `.trellis/spec/` or a project-local skill. |
+| Change Trellis flow semantics | Synchronize `.trellis/workflow.md`. |
+
+## Modify A Skill
+
+A skill is usually:
+
+```text
+<skill-name>/
+├── SKILL.md
+└── references/
+```
+
+`SKILL.md` should be short and responsible for triggering/routing. Put long content in `references/` so AI can read it on demand.
+
+The frontmatter description should specify when to use the skill. Example:
+
+```yaml
+description: "Use when customizing this project's deployment workflow and release checklist."
+```
+
+Do not write vague descriptions such as "helpful project skill"; they can trigger incorrectly.
+
+## Modify A Command/Prompt/Workflow
+
+Explicit entry points should state:
+
+- How the user triggers it.
+- Which `.trellis/` files to read.
+- Which scripts to run.
+- How to report after completion.
+
+If a command only repeats workflow rules, prefer making it reference/read `.trellis/workflow.md` instead of maintaining a second copy of the flow.
+
+## Common Paths
+
+| Platform | Entry directories |
+| --- | --- |
+| Claude Code | `.claude/skills/`, `.claude/commands/` |
+| Cursor | `.cursor/skills/`, `.cursor/commands/` |
+| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
+| Codex | `.agents/skills/`, `.codex/skills/` |
+| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
+| Kilo / Antigravity / Windsurf | workflows + skills |
+
+## Add A Project-Local Skill
+
+If the user wants to document team-private customizations, create a project-local skill, for example:
+
+```text
+.claude/skills/project-trellis-local/
+└── SKILL.md
+```
+
+For multi-platform projects, add equivalent versions in each platform skill directory, or use `.agents/skills/` on platforms that support the shared layer.
+
+## Notes
+
+- Do not mix every platform's syntax into one file.
+- Do not change only one platform entry point while claiming all platforms are supported.
+- Do not hide long-term engineering conventions inside a command; write them to `.trellis/spec/`.
@@ -0,0 +1,83 @@
+# Change Local Spec Structure
+
+When the user wants to change the engineering conventions AI follows, add new spec layers, or adjust monorepo package mapping, edit `.trellis/spec/` and `.trellis/config.yaml`.
+
+## Read These Files First
+
+1. `.trellis/config.yaml`
+2. `.trellis/spec/`
+3. `.trellis/workflow.md` Phase 1.3 and Phase 3.3
+4. Current task `implement.jsonl` / `check.jsonl`
+
+## Common Needs
+
+| Need | Edit location |
+| --- | --- |
+| Add backend/frontend/docs/test spec layer | `.trellis/spec/<layer>/` or `.trellis/spec/<package>/<layer>/` |
+| Add shared thinking guides | `.trellis/spec/guides/` |
+| Adjust monorepo packages | `packages` in `.trellis/config.yaml` |
+| Change default package | `default_package` in `.trellis/config.yaml` |
+| Control spec scanning scope | `spec_scope` in `.trellis/config.yaml` |
+| Make a task read a new spec | Task `implement.jsonl` / `check.jsonl` |
+
+## Add A Spec Layer
+
+Single-repository example:
+
+```text
+.trellis/spec/security/
+├── index.md
+└── auth.md
+```
+
+Monorepo example:
+
+```text
+.trellis/spec/webapp/security/
+├── index.md
+└── auth.md
+```
+
+`index.md` should include:
+
+- What code this layer applies to.
+- Pre-Development Checklist.
+- Quality Check.
+- Links to specific guideline files.
+
+## Update Context
+
+Adding a spec does not mean every task automatically reads it. The current task must reference it in JSONL:
+
+```bash
+python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/webapp/security/index.md" "Security conventions"
+python3 ./.trellis/scripts/task.py add-context <task> check ".trellis/spec/webapp/security/index.md" "Security review rules"
+```
+
+## Change Monorepo Packages
+
+Example `.trellis/config.yaml`:
+
+```yaml
+packages:
+  webapp:
+    path: apps/web
+  api:
+    path: apps/api
+default_package: webapp
+```
+
+After editing, run:
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+Use this output to confirm AI can see the correct packages and spec layers.
+
+## Notes
+
+- Specs are user project conventions and can be changed according to project needs.
+- Do not put temporary task information into specs; put temporary information in the task.
+- Do not put long-term conventions only in agents or commands; preserve them in specs.
+- After changing spec structure, check whether existing task JSONL files still point to files that exist.
@@ -0,0 +1,90 @@
+# 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 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`
+
+## Common Needs And 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`. |
+| 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`. |
+
+## lifecycle hooks
+
+`.trellis/config.yaml` supports:
+
+```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"
+```
+
+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.
+
+## Change Task Fields
+
+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.
+
+Example:
+
+```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.
@@ -0,0 +1,64 @@
+# 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 These Files First
+
+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`
+
+## Common Needs And Edit Points
+
+| 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.
+
+## Example: One Platform Does Not Use Sub-Agents
+
+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` | `prd.md` exists, `implement.jsonl` only has the seed `_example` row | Phase 1.3 (curate JSONL context) |
+| `planning` | `prd.md` exists, `implement.jsonl` curated | Phase 1.4 (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.1 (verify quality + spec update) |
+| `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
+
+`.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.
@@ -0,0 +1,55 @@
+# Local Customization Overview
+
+This directory is for local AI working in a user project where Trellis was installed through npm and `trellis init` has already been run. The AI should modify generated `.trellis/` and platform directories inside the project, not Trellis CLI upstream source code.
+
+## First Determine What The User Actually Wants To Change
+
+| 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` |
+| "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` |
+| "Add a skill/command/workflow/prompt" | `change-skills-or-commands.md` |
+| "Adjust the project spec structure" | `change-spec-structure.md` |
+| "Add team conventions and local notes" | `add-project-local-conventions.md` |
+
+## General Operation Order
+
+1. **Confirm platform and directories**: inspect which directories exist, such as `.claude/`, `.codex/`, `.cursor/`.
+2. **Confirm the current active task**: run `python3 ./.trellis/scripts/task.py current --source`.
+3. **Read the local source of truth**: prefer `.trellis/workflow.md`, `.trellis/config.yaml`, and relevant platform files.
+4. **Modify narrowly**: edit only files related to the user's request.
+5. **Synchronize semantics**: if a shared flow changes, check whether platform entry points also need changes; if a platform entry changes, check whether `.trellis/workflow.md` still agrees.
+
+## Local File Priority
+
+| Layer | Files |
+| --- | --- |
+| Workflow | `.trellis/workflow.md` |
+| Project configuration | `.trellis/config.yaml` |
+| Task material | `.trellis/tasks/<task>/` |
+| Project specs | `.trellis/spec/` |
+| Runtime scripts | `.trellis/scripts/` |
+| Platform integration | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, and similar directories |
+| Shared skill | `.agents/skills/` |
+
+## Things Not To Do By Default
+
+- Do not edit the global npm install directory.
+- Do not edit `node_modules/@mindfoldhq/trellis`.
+- Do not assume the user has the Trellis GitHub repository.
+- Do not overwrite local files already modified by the user with default templates.
+- Do not put team project rules into public `trellis-meta`; project rules belong in `.trellis/spec/` or a local skill.
+
+## When To Inspect Upstream Source
+
+Switch to an upstream source-code perspective only when the user explicitly expresses one of these goals:
+
+- "I want to open a PR to Trellis"
+- "I want to change npm package publish contents"
+- "I want to fork Trellis"
+- "I want to modify the generation logic for `trellis init/update`"
+
+Otherwise, default to modifying local Trellis files inside the user project.