@mindfoldhq/trellis 0.5.0-beta.16 → 0.5.0-beta.18

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

@@ -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.

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

@@ -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/`.

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

@@ -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.

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

@@ -0,0 +1,79 @@
+# 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`
+
+## 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.

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

@@ -0,0 +1,48 @@
+# 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. If workflow-state prompt blocks change, confirm hooks can still read blocks by status.
+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.
+
+## 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.

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

@@ -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.

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

@@ -0,0 +1,68 @@
+# Local Context Injection System
+
+Trellis context injection aims to make AI read the right files at the right time instead of relying on model memory. In a user project, injection is implemented by `.trellis/` scripts together with platform hooks, agents, and skills.
+
+## Injected Context Types
+
+| Type | Source | Purpose |
+| --- | --- | --- |
+| session context | `.trellis/scripts/get_context.py` | Current developer, git status, active task, active tasks, journal, packages. |
+| workflow context | `.trellis/workflow.md` | Current Trellis flow and next action. |
+| spec context | `.trellis/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
+| task context | `.trellis/tasks/<task>/prd.md`, `info.md`, `research/` | Current task requirements, design, and research. |
+| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
+
+## session-start
+
+Platforms with session-start support inject a Trellis overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
+
+- workflow summary.
+- current task status.
+- active tasks.
+- spec index paths.
+- developer identity and git status.
+
+If the user feels the AI does not know the current task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
+
+## workflow-state
+
+workflow-state is a lightweight hint injected around each user turn. Based on current task status, it selects a block from `.trellis/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
+
+If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.trellis/workflow.md` first.
+
+## sub-agent context
+
+Implement and check agents need task context. Trellis has two loading modes:
+
+1. **hook push**: a platform hook injects `prd.md` and the files referenced by `implement.jsonl` / `check.jsonl` before the agent starts.
+2. **agent pull**: the agent definition instructs the agent to read the active task, PRD, and JSONL context after startup.
+
+In both modes, JSONL files in the task directory are the key interface.
+
+## JSONL Reading Rules
+
+`implement.jsonl` and `check.jsonl` contain one JSON object per line:
+
+```jsonl
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend rules"}
+```
+
+Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
+
+## Active Task And Context Key
+
+Active task state lives in `.trellis/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `TRELLIS_CONTEXT_ID`.
+
+If shell commands cannot see the same context key, `task.py current --source` may report no active task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change session-start injected content | The platform's `session-start` hook or plugin file. |
+| Change per-turn workflow-state rules | State blocks in `.trellis/workflow.md` and the platform workflow-state hook. |
+| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
+| Change JSONL validation/display | `.trellis/scripts/common/task_context.py`. |
+| Change active task resolution | `.trellis/scripts/common/active_task.py`. |
+
+When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct PRD/spec/research.

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

@@ -0,0 +1,80 @@
+# Local Files Generated After Init
+
+`trellis init` writes the Trellis runtime into the user project. Later, `trellis update` tries to update Trellis-managed template files, but it uses `.trellis/.template-hashes.json` to determine which files have already been modified by the user.
+
+This page only describes files that are visible and editable inside the user project.
+
+## `.trellis/`
+
+```text
+.trellis/
+├── workflow.md
+├── config.yaml
+├── .developer
+├── .version
+├── .template-hashes.json
+├── .runtime/
+├── scripts/
+├── spec/
+├── tasks/
+└── workspace/
+```
+
+| Path | Usually editable? | Notes |
+| --- | --- | --- |
+| `.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/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`. |
+| `.trellis/scripts/` | Carefully | Local runtime. It can be customized, but only after understanding the call chain. |
+| `.trellis/.runtime/` | No | Runtime state, usually written automatically by hooks/scripts. |
+| `.trellis/.developer` | Carefully | Current developer identity. |
+| `.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. |
+
+## Platform Directories
+
+Different platforms generate different directories. Common categories:
+
+| Category | Example paths | Purpose |
+| --- | --- | --- |
+| hooks | `.claude/hooks/`, `.codex/hooks/`, `.cursor/hooks/` | Inject session context, workflow-state, and sub-agent context. |
+| settings | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Tell the platform when to run hooks or plugins. |
+| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
+| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Skills that auto-trigger or can be read by AI. |
+| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Explicit user-invoked command or workflow entry points. |
+
+When modifying a platform directory, also confirm whether `.trellis/workflow.md` still describes the same flow.
+
+## Meaning Of Template Hashes
+
+`.trellis/.template-hashes.json` records the content hash from the last time Trellis wrote a template file. `trellis update` uses it to distinguish three cases:
+
+| Case | Update behavior |
+| --- | --- |
+| File was not modified by the user | It can be updated automatically. |
+| File was modified by the user | Prompt the user to overwrite, keep, or generate `.new`. |
+| File is no longer a current template | It may be deleted, renamed, or preserved according to migration rules. |
+
+When an AI customizes local Trellis files, it does not need to maintain hashes manually. It is normal for Trellis update to recognize the result as "modified by the user."
+
+## Local Customization Boundaries
+
+Editable by default:
+
+- `.trellis/workflow.md`
+- `.trellis/config.yaml`
+- `.trellis/spec/**`
+- `.trellis/scripts/**`
+- Platform hooks, settings, agents, skills, commands, prompts, and workflows
+
+Do not edit by default:
+
+- Global npm install directory
+- `node_modules/@mindfoldhq/trellis`
+- Trellis GitHub repository source code
+- Concrete state files under `.trellis/.runtime/**`
+- Hash contents inside `.trellis/.template-hashes.json`
+
+Switch to the Trellis CLI source-code perspective only when the user explicitly wants to contribute upstream.

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

@@ -0,0 +1,51 @@
+# Local Trellis Architecture Overview
+
+`trellis-meta` is for user projects that have already run `trellis init`. The user's machine usually has only the npm-installed `trellis` command plus the Trellis files generated inside the project; it may not have the Trellis CLI source code.
+
+Therefore, when an AI uses this skill, the default customization target is local files inside the user project:
+
+- `.trellis/`: workflow, tasks, specs, memory, scripts, and runtime state.
+- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
+- Shared skill layer: `.agents/skills/`.
+
+Do not default to guiding the user to fork the Trellis CLI repository. Treat upstream source code as the operating target only when the user explicitly says they want to change Trellis upstream source, publish an npm package, or contribute a PR.
+
+## Local System Model
+
+Trellis provides three layers inside a user project:
+
+1. **Workflow layer**: `.trellis/workflow.md` defines phases, routing, next actions, and prompt blocks.
+2. **Persistence layer**: `.trellis/tasks/`, `.trellis/spec/`, and `.trellis/workspace/` store tasks, specs, and session memory.
+3. **Platform integration layer**: hooks, settings, agents, skills, commands, prompts, and workflows in platform directories connect the Trellis workflow to different AI tools.
+
+All three layers live inside the user project, so an AI can read and modify them directly.
+
+## Core Paths
+
+| Path | Purpose |
+| --- | --- |
+| `.trellis/workflow.md` | Workflow phases, skill routing, and workflow-state prompt blocks. |
+| `.trellis/config.yaml` | Project configuration, task lifecycle hooks, monorepo package configuration, and journal configuration. |
+| `.trellis/spec/` | The user's project-specific coding conventions and thinking guides. |
+| `.trellis/tasks/` | Each task's PRD, technical notes, research files, and JSONL context. |
+| `.trellis/workspace/` | Per-developer journals and cross-session memory. |
+| `.trellis/scripts/` | Local Python runtime used by commands, hooks, and context injection. |
+| `.trellis/.runtime/` | Session-level runtime state, such as the current task pointer. |
+| `.trellis/.template-hashes.json` | Template hashes for Trellis-managed files, used by update to determine whether local files were modified by the user. |
+
+## AI Customization Principles
+
+1. **Find the local source of truth first**: Do not edit from memory. Read `.trellis/workflow.md`, `.trellis/config.yaml`, the relevant platform directory, and related task files first.
+2. **Edit the user project, not the npm package cache**: Modify generated files inside the project, not `node_modules` or the global npm install directory.
+3. **Keep platform files aligned with `.trellis/`**: If workflow routing changes, also check whether platform skills or commands still describe the same flow.
+4. **Put project-specific rules in `.trellis/spec/` or a local skill**: Do not put team conventions into `trellis-meta`.
+5. **Preserve user changes**: If a file was already modified locally, work from the current content instead of overwriting it with a default template.
+
+## How To Use This Directory
+
+- To understand which files exist after init, read `generated-files.md`.
+- To change phases, routing, or next actions, read `workflow.md`.
+- To change the task model, JSONL context, or active task behavior, read `task-system.md`.
+- To change coding convention injection, read `spec-system.md`.
+- To understand journals and cross-session memory, read `workspace-memory.md`.
+- To change hooks or sub-agent context loading, read `context-injection.md`.