@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-rc.0

package/dist/templates/codex/skills/finish-work/SKILL.md

@@ -1,148 +1,80 @@
 ---
 name: finish-work
-description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
+description: "Wrap up an active Trellis task: archive it (and any other completed-but-unarchived tasks the user wants to clean up) and record a session journal. Refuses to run if the working tree has uncommitted code changes (those belong in workflow Phase 3.4 first). Use when the user asks to finish / wrap up / call it a day, or invokes $finish-work."
 ---
 
-# Finish Work - Pre-Commit Checklist
+# Finish Work
 
-Before submitting or committing, use this checklist to ensure work completeness.
+Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this skill.
 
-**Timing**: After code is written and tested, before commit
-
----
-
-## Checklist
-
-### 1. Code Quality
+## Step 1: Survey current state
 
 ```bash
-# Must pass
-pnpm lint
-pnpm type-check
-pnpm test
+python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-- [ ] `pnpm lint` passes with 0 errors?
-- [ ] `pnpm type-check` passes with no type errors?
-- [ ] Tests pass?
-- [ ] No `console.log` statements (use logger)?
-- [ ] No non-null assertions (the `x!` operator)?
-- [ ] No `any` types?
-
-### 2. Code-Spec Sync
-
-**Code-Spec Docs**:
-- [ ] Does `.trellis/spec/backend/` need updates?
-  - New patterns, new modules, new conventions
-- [ ] Does `.trellis/spec/frontend/` need updates?
-  - New components, new hooks, new patterns
-- [ ] Does `.trellis/spec/guides/` need updates?
-  - New cross-layer flows, lessons from bugs
-
-**Key Question**: 
-> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
+This prints:
 
-If YES -> Update the relevant code-spec doc.
+- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
+- **Git status** — quick visual on what's dirty.
+- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
 
-### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
+If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
 
-If this change touches infra or cross-layer contracts, this is a blocking checklist:
+## Step 2: Sanity check — working tree must be clean
 
-- [ ] Spec content is executable (real signatures/contracts), not principle-only text
-- [ ] Includes file path + command/API name + payload field names
-- [ ] Includes validation and error matrix
-- [ ] Includes Good/Base/Bad cases
-- [ ] Includes required tests and assertion points
+Run:
 
-**Block Rule**:
-If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `$update-spec` manually first.
-
-### 3. API Changes
-
-If you modified API endpoints:
-
-- [ ] Input schema updated?
-- [ ] Output schema updated?
-- [ ] API documentation updated?
-- [ ] Client code updated to match?
-
-### 4. Database Changes
+```bash
+git status --porcelain
+```
 
-If you modified database schema:
+Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
 
-- [ ] Migration file created?
-- [ ] Schema file updated?
-- [ ] Related queries updated?
-- [ ] Seed data updated (if applicable)?
+If anything else is dirty (any path outside those two prefixes), **stop and bail out** with:
 
-### 5. Cross-Layer Verification
+> "Working tree has uncommitted code changes. Return to workflow Phase 3.4 to commit them before running `$finish-work`."
 
-If the change spans multiple layers:
+Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
 
-- [ ] Data flows correctly through all layers?
-- [ ] Error handling works at each boundary?
-- [ ] Types are consistent across layers?
-- [ ] Loading states handled?
+## Step 3: Archive task(s)
 
-### 6. Manual Testing
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
 
-- [ ] Feature works in browser/app?
-- [ ] Edge cases tested?
-- [ ] Error states tested?
-- [ ] Works after page refresh?
+At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
 
----
+If there is no active task and the user did not confirm any cleanup archives, skip this step.
 
-## Quick Check Flow
+## Step 4: Record session journal
 
 ```bash
-# 1. Code checks
-pnpm lint && pnpm type-check
-
-# 2. View changes
-git status
-git diff --name-only
-
-# 3. Based on changed files, check relevant items above
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
 ```
 
----
-
-## Common Oversights
+Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
 
-| Oversight | Consequence | Check |
-|-----------|-------------|-------|
-| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ |
-| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
-| Migration not created | Schema out of sync | Check db/migrations/ |
-| Types not synced | Runtime errors | Check shared types |
-| Tests not updated | False confidence | Run full test suite |
-| Console.log left in | Noisy production logs | Search for console.log |
+Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
 
 ---
 
-## Relationship to Other Commands
+## Relationship to Other Skills
 
 ```
 Development Flow:
-  Write code -> Test -> $finish-work -> git commit -> $record-session
-                          |                              |
-                   Ensure completeness              Record progress
-                   
+  Phase 3.4 (workflow.md) -> AI drafts batched commits -> user confirms -> git commit
+                                                                              |
+                                                                              v
+                                                                    $finish-work
+                                                                    (survey + archive + journal)
+
 Debug Flow:
   Hit bug -> Fix -> $break-loop -> Knowledge capture
-                       |
-                  Deep analysis
 ```
 
-- `$finish-work` - Check work completeness (this skill)
-- `$record-session` - Record session and commits
-- `$break-loop` - Deep analysis after debugging
-
----
-
-## Core Principle
-
-> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
-
-Complete work = Code + Docs + Tests + Verification
+- `$finish-work` — this skill, survey + archive + record session
+- `$break-loop` — deep analysis after debugging

package/dist/templates/codex/skills/start/SKILL.md

@@ -244,17 +244,21 @@ Use this output format:
 
 **Step 6: Configure Context** `[AI]`
 
-Initialize default context:
+`implement.jsonl` and `check.jsonl` were seeded on `task.py create` with a single self-describing `_example` line. Curate real entries now (see workflow.md Phase 1.3 for the full rule):
+
+- Put **spec files** (`.trellis/spec/<package>/<layer>/*.md`) and **research files** (`{TASK_DIR}/research/*.md`) only.
+- Do NOT put code files (`src/**`, `packages/**`) — those are read during implementation, not pre-registered here.
+- Split: `implement.jsonl` = specs the implement sub-agent needs; `check.jsonl` = specs the check sub-agent needs.
+
+Discover available specs:
 
 ```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
-# type: backend | frontend | fullstack
+python3 ./.trellis/scripts/get_context.py --mode packages
 ```
 
-Add specs found in your research pass:
+Append entries (either edit the jsonl file directly, or):
 
 ```bash
-# For each relevant spec and code pattern:
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
 ```
@@ -265,7 +269,7 @@ python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reas
 python3 ./.trellis/scripts/task.py start "$TASK_DIR"
 ```
 
-This sets `.current-task` so hooks can inject context.
+This sets the active task through Trellis' session resolver so hooks can inject context for this AI session. If the command fails because no session identity is available, rerun it from an IDE/session that exposes session identity or set `TRELLIS_CONTEXT_ID`.
 
 ---
 
@@ -325,9 +329,8 @@ If yes, resume from the appropriate step (usually Step 7 or 8).
 | Script | Purpose |
 |--------|---------|
 | `python3 ./.trellis/scripts/get_context.py` | Get session context |
-| `python3 ./.trellis/scripts/task.py create` | Create task directory |
-| `python3 ./.trellis/scripts/task.py init-context` | Initialize jsonl files |
-| `python3 ./.trellis/scripts/task.py add-context` | Add spec to jsonl |
+| `python3 ./.trellis/scripts/task.py create` | Create task directory (seeds jsonl on sub-agent platforms) |
+| `python3 ./.trellis/scripts/task.py add-context` | Append spec/research entry to jsonl |
 | `python3 ./.trellis/scripts/task.py start` | Set current task |
 | `python3 ./.trellis/scripts/task.py finish` | Clear current task |
 | `python3 ./.trellis/scripts/task.py archive` | Archive completed task |

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

@@ -0,0 +1,73 @@
+---
+name: trellis-meta
+description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, or workflows generated by trellis init."
+---
+
+# Trellis Meta
+
+This skill is for local Trellis users who have already run `trellis init` in a project. After reading it, an AI should understand the Trellis architecture, operating model, and customization entry points inside that user project, then modify the generated `.trellis/` and platform directory files according to the user's request.
+
+The default operating scope is local files in the user project:
+
+- `.trellis/`: workflow, config, tasks, spec, workspace, 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 assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules`.
+
+## How To Use
+
+1. Read `references/local-architecture/overview.md` first to establish the local Trellis system model.
+2. If the request involves a specific AI tool, read `references/platform-files/platform-map.md` and the relevant platform file notes.
+3. If the user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic.
+4. Before editing, read the actual files in the user project and treat local content as authoritative.
+
+## References
+
+### Local Architecture
+
+- `references/local-architecture/overview.md`: The three-layer local Trellis architecture and customization principles.
+- `references/local-architecture/generated-files.md`: Files generated by `trellis init` and their customization boundaries.
+- `references/local-architecture/workflow.md`: Phases, routing, and workflow-state blocks in `.trellis/workflow.md`.
+- `references/local-architecture/task-system.md`: Task directories, active tasks, JSONL context, and task runtime.
+- `references/local-architecture/spec-system.md`: How `.trellis/spec/` is organized and injected.
+- `references/local-architecture/workspace-memory.md`: `.trellis/workspace/`, journals, and cross-session memory.
+- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and context injection paths.
+
+### Platform Files
+
+- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories.
+- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions.
+- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis.
+- `references/platform-files/agents.md`: Local file responsibilities for `trellis-research`, `trellis-implement`, and `trellis-check`.
+- `references/platform-files/skills-and-commands.md`: Differences between skills, commands, prompts, and workflows, plus how to change them.
+
+### Local Customization
+
+- `references/customize-local/overview.md`: Choose the right local customization entry point for the user's request.
+- `references/customize-local/change-workflow.md`: Change phases, routing, next actions, and workflow-state.
+- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, and hooks.
+- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, and hook context are loaded.
+- `references/customize-local/change-hooks.md`: Change platform hooks, settings, and shell session bridges.
+- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior.
+- `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows.
+- `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.trellis/spec/`.
+- `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills.
+
+## Current Rules
+
+- `.trellis/workflow.md` is the local workflow source of truth.
+- `.trellis/config.yaml` is the project-level Trellis configuration and task hook configuration entry point.
+- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints.
+- `.trellis/tasks/` stores task PRDs, technical notes, research files, and JSONL context.
+- `.trellis/workspace/` stores developer journals and cross-session memory.
+- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run.
+- `.trellis/.template-hashes.json` and `.trellis/.runtime/` are management/runtime state files. Confirm necessity before editing them.
+
+## Do Not
+
+- Do not treat Trellis upstream source code as the default target for local customization.
+- Do not modify the global npm install directory or `node_modules/@mindfoldhq/trellis` to implement project needs.
+- Do not overwrite user-modified local files with default templates.
+- Do not put team-private project rules into the public `trellis-meta`; put project rules in `.trellis/spec/` or a project-local skill.
+- Do not describe removed historical mechanisms as current Trellis behavior.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/add-project-local-conventions.md

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

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

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

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

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

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.