@blxzer/pactile 0.5.0 → 0.6.0-beta.4

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

@@ -1,75 +1,75 @@
----
-name: pactile-meta
-description: "Understand and customize the local Pactile architecture inside a user project. Use when modifying .pactile plus platform hooks, settings, agents, skills, commands, prompts, or workflows generated by pactile init."
----
-
-# Pactile Meta
-
-This skill is for local Pactile users who have already run `pactile init` in a project. After reading it, an AI should understand the Pactile architecture, operating model, and customization entry points inside that user project, then modify the generated `.pactile/` and platform directory files according to the user's request.
-
-The default operating scope is local files in the user project:
-
-- `.pactile/`: workflow, config, tasks, spec, workspace, scripts, and runtime state.
-- Platform directory: `.cursor/` — skills, agents, hooks, commands, rules.
-- Shared skill layer: `.agents/skills/` (industry skill-sharing path, kept when present but not extended by new Pactile behavior).
-
-Pactile previously supported many AI-platform adapter directories (`.claude/`, `.codex/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`). The project has converged on **Cursor-only**. Legacy adapter directories in upgraded projects are preserved by `pactile update` but new Pactile behavior ships to `.cursor/` only.
-
-Do not assume the user has the Pactile 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 Pactile 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 Pactile architecture and customization principles.
-- `references/local-architecture/generated-files.md`: Files generated by `pactile init` and their customization boundaries.
-- `references/local-architecture/workflow.md`: Phases, routing, and workflow-state blocks in `.pactile/workflow.md`.
-- `references/local-architecture/task-system.md`: Task directories, selected tasks, JSONL context, and task runtime.
-- `references/local-architecture/spec-system.md`: How `.pactile/spec/` is organized and injected.
-- `references/local-architecture/workspace-memory.md`: `.pactile/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 `.pactile/` 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 Pactile.
-- `references/platform-files/agents.md`: Local file responsibilities for `pactile-research`, `pactile-implement`, and `pactile-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 `.pactile/spec/`.
-- `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills.
-
-## Current Rules
-
-- `.pactile/workflow.md` is the local workflow source of truth.
-- `.pactile/config.yaml` is the project-level Pactile configuration and task hook configuration entry point.
-- `.pactile/spec/` stores the user's project-specific coding conventions and design constraints.
-- `.pactile/tasks/` stores task PRDs, technical notes, research files, and JSONL context.
-- `.pactile/workspace/` stores developer journals and cross-session memory.
-- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run.
-- `.pactile/.template-hashes.json` and `.pactile/.runtime/` are management/runtime state files. Confirm necessity before editing them.
-
-## Do Not
-
-- Do not treat Pactile upstream source code as the default target for local customization.
-- Do not modify the global npm install directory or `node_modules/@blxzer/pactile` to implement project needs.
-- Do not overwrite user-modified local files with default templates.
-- Do not put team-private project rules into the public `pactile-meta`; put project rules in `.pactile/spec/` or a project-local skill.
-- Do not describe removed historical mechanisms as current Pactile behavior.
+---
+name: pactile-meta
+description: "Understand and customize the local Pactile architecture inside a user project. Use when modifying .pactile plus platform hooks, settings, agents, skills, commands, prompts, or workflows generated by pactile init."
+---
+
+# Pactile Meta
+
+This skill is for local Pactile users who have already run `pactile init` in a project. After reading it, an AI should understand the Pactile architecture, operating model, and customization entry points inside that user project, then modify the generated `.pactile/` and platform directory files according to the user's request.
+
+The default operating scope is local files in the user project:
+
+- `.pactile/`: workflow, config, tasks, spec, workspace, scripts, and runtime state.
+- Codex project entry: managed `AGENTS.md` content and `.agents/skills/`.
+- Optional native Codex configuration only when a reviewed projection declares it and readiness succeeds.
+
+Codex is the current installation target. Legacy host directories in upgraded projects remain user-reviewable and are not refreshed as active adapters.
+
+Do not assume the user has the Pactile 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 Pactile 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 Pactile architecture and customization principles.
+- `references/local-architecture/generated-files.md`: Files generated by `pactile init` and their customization boundaries.
+- `references/local-architecture/workflow.md`: Phases, routing, and workflow-state blocks in `.pactile/workflow.md`.
+- `references/local-architecture/task-system.md`: Task directories, selected tasks, JSONL context, and task runtime.
+- `references/local-architecture/spec-system.md`: How `.pactile/spec/` is organized and injected.
+- `references/local-architecture/workspace-memory.md`: `.pactile/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 `.pactile/` 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 Pactile.
+- `references/platform-files/agents.md`: Local file responsibilities for `pactile-research`, `pactile-implement`, and `pactile-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 `.pactile/spec/`.
+- `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills.
+
+## Current Rules
+
+- `.pactile/workflow.md` is the local workflow source of truth.
+- `.pactile/config.yaml` is the project-level Pactile configuration and task hook configuration entry point.
+- `.pactile/spec/` stores the user's project-specific coding conventions and design constraints.
+- `.pactile/tasks/` stores task PRDs, technical notes, research files, and JSONL context.
+- `.pactile/workspace/` stores developer journals and cross-session memory.
+- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run.
+- `.pactile/.template-hashes.json` and `.pactile/.runtime/` are management/runtime state files. Confirm necessity before editing them.
+
+## Do Not
+
+- Do not treat Pactile upstream source code as the default target for local customization.
+- Do not modify the global npm install directory or `node_modules/@blxzer/pactile` to implement project needs.
+- Do not overwrite user-modified local files with default templates.
+- Do not put team-private project rules into the public `pactile-meta`; put project rules in `.pactile/spec/` or a project-local skill.
+- Do not describe removed historical mechanisms as current Pactile behavior.

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

@@ -1,83 +1,83 @@
-# Add Project-Local Conventions
-
-Often the user does not need to change Pactile mechanics; they need local AI to understand their team's conventions. In that case, prefer `.pactile/spec/` or a project-local skill instead of editing `pactile-meta`.
-
-## Where To Put Things
-
-| Content type | Location |
-| --- | --- |
-| Rules code must follow | `.pactile/spec/<layer>/` |
-| Cross-layer thinking methods | `.pactile/spec/guides/` |
-| AI capability for a project-specific flow | Platform-local skill |
-| One-off task material | `.pactile/tasks/<task>/` |
-| Session summary | `.pactile/workspace/<developer>/journal-N.md` |
-
-## Create A Project-Local Skill
-
-If the user wants AI to know "how this project customizes Pactile," create a local skill:
-
-```text
-.claude/skills/pactile-local/
-└── SKILL.md
-```
-
-Example:
-
-```md
----
-name: pactile-local
-description: "Project-local Pactile customizations for this repository. Use when changing this project's Pactile workflow, hooks, local agents, or team-specific conventions."
----
-
-# Pactile Local
-
-## Local Scope
-
-This skill documents this repository's Pactile 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 `.pactile/spec/`
-
-If the content is a coding convention, write it to spec. Examples:
-
-```text
-.pactile/spec/backend/error-handling.md
-.pactile/spec/frontend/components.md
-.pactile/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 Selected Task Use New Conventions
-
-After writing a spec, add it to the selected task context:
-
-```bash
-python3 ./.pactile/scripts/task.py add-context <task> implement ".pactile/spec/backend/error-handling.md" "Error handling conventions"
-python3 ./.pactile/scripts/task.py add-context <task> check ".pactile/spec/backend/error-handling.md" "Review error handling"
-```
-
-## Do Not Store Project-Private Rules In `pactile-meta`
-
-`pactile-meta` is a public skill for understanding Pactile architecture and local customization entry points. Put project-private content in:
-
-- `.pactile/spec/`
-- a project-local skill
-- the selected task
-- workspace journal
-
-This prevents future updates to Pactile's built-in `pactile-meta` from overwriting the team's own conventions.
+# Add Project-Local Conventions
+
+Often the user does not need to change Pactile mechanics; they need local AI to understand their team's conventions. In that case, prefer `.pactile/spec/` or a project-local skill instead of editing `pactile-meta`.
+
+## Where To Put Things
+
+| Content type | Location |
+| --- | --- |
+| Rules code must follow | `.pactile/spec/<layer>/` |
+| Cross-layer thinking methods | `.pactile/spec/guides/` |
+| AI capability for a project-specific flow | Platform-local skill |
+| One-off task material | `.pactile/tasks/<task>/` |
+| Session summary | `.pactile/workspace/<developer>/journal-N.md` |
+
+## Create A Project-Local Skill
+
+If the user wants AI to know "how this project customizes Pactile," create a local skill:
+
+```text
+.claude/skills/pactile-local/
+└── SKILL.md
+```
+
+Example:
+
+```md
+---
+name: pactile-local
+description: "Project-local Pactile customizations for this repository. Use when changing this project's Pactile workflow, hooks, local agents, or team-specific conventions."
+---
+
+# Pactile Local
+
+## Local Scope
+
+This skill documents this repository's Pactile 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 `.pactile/spec/`
+
+If the content is a coding convention, write it to spec. Examples:
+
+```text
+.pactile/spec/backend/error-handling.md
+.pactile/spec/frontend/components.md
+.pactile/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 Selected Task Use New Conventions
+
+After writing a spec, add it to the selected task context:
+
+```bash
+pactile task add-context <task> implement ".pactile/spec/backend/error-handling.md" "Error handling conventions"
+pactile task add-context <task> check ".pactile/spec/backend/error-handling.md" "Review error handling"
+```
+
+## Do Not Store Project-Private Rules In `pactile-meta`
+
+`pactile-meta` is a public skill for understanding Pactile architecture and local customization entry points. Put project-private content in:
+
+- `.pactile/spec/`
+- a project-local skill
+- the selected task
+- workspace journal
+
+This prevents future updates to Pactile's built-in `pactile-meta` from overwriting the team's own conventions.

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

@@ -1,47 +1,5 @@
-# Change Local Agents
-
-When the user wants to change `pactile-research`, `pactile-implement`, or `pactile-check` behavior, edit platform agent files in the user project.
-
-## Read These Files First
-
-1. Target platform agent directory
-2. `.pactile/workflow.md` Phase 2 / research routing
-3. Selected task `prd.md`
-4. Selected task `implement.jsonl` / `check.jsonl`
-5. Relevant hook or agent prelude
-
-## Common Paths
-
-| Platform | Path |
-| --- | --- |
-| Cursor | `.cursor/agents/pactile-*.md` |
-
-If a user project still contains legacy platform agent directories (`.claude/agents/`, `.codex/agents/`, etc.), inspect them but route new agent definitions to `.cursor/agents/`.
-
-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 | `pactile-research` |
-| Certain local specs must be read before implementation | `pactile-implement` + `implement.jsonl` configuration rules |
-| Specific commands must run during checking | `pactile-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 `.pactile/spec/`; agents are responsible for reading them.
-3. **Make read order explicit**: selected task -> PRD -> info -> JSONL -> spec/research.
-4. **Make write boundaries explicit**: which directories may be written and which may not.
-5. **Treat dogfood + published copies consistently**: `.cursor/agents/pactile-*.md` (dogfooded) and `packages/cli/src/templates/cursor/agents/pactile-*.md` (published template) must stay in sync — see `cross-layer-thinking-guide.md.txt` → Cross-Package Template Consistency.
-
-## Agent Pull Mode
-
-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 Pactile's core mechanism.
-
-## Hook Push Mode
-
-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.
+# Change worker behavior
+
+For current Codex work, change the approved task contract and the instructions delivered to an independent desktop task. Record objective, write set, validation, and integration owner.
+
+Use `pactile codex prepare|receipt|status` to bind independent desktop tasks to the Pactile lifecycle. The App task invokes native tools; no local template automatically dispatches them. Do not create Codex subagent roles. Preserve legacy host files unless an explicit detach plan owns them.

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

@@ -1,84 +1,79 @@
-# 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 selected task," "the agent did not read specs," or "there is too much/too little context."
-
-## Read These Files First
-
-1. `.pactile/workflow.md`
-2. `.pactile/scripts/get_context.py`
-3. `.pactile/scripts/common/session_context.py`
-4. `.pactile/scripts/common/task_context.py`
-5. `.pactile/scripts/common/active_task.py`
-6. Current platform hooks or agent files
-7. The selected task's `implement.jsonl` / `check.jsonl`
-
-## Context Sources
-
-| Source | Purpose |
-| --- | --- |
-| `.pactile/workflow.md` | Workflow and next-action hints. |
-| `.pactile/tasks/<task>/prd.md` | Selected task requirements. |
-| `.pactile/tasks/<task>/design.md` | Complex task technical design. |
-| `.pactile/tasks/<task>/implement.md` | Complex task execution plan. |
-| `.pactile/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
-| `.pactile/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
-| `.pactile/spec/` | Project specs. |
-| `.pactile/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 `.pactile/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. |
-| Selected 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": ".pactile/spec/backend/index.md", "reason": "Backend conventions"}
-{"file": ".pactile/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:
-
-- `.pactile/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 `pactile-implement` / `pactile-check` agent file.
-
-In both modes, make sure the agent ultimately reads:
-
-1. selected task
-2. the corresponding JSONL
-3. spec/research referenced by the JSONL
-4. `prd.md`
-5. `design.md` if present
-6. `implement.md` if present
-
-## Troubleshooting Order
-
-```bash
-python3 ./.pactile/scripts/task.py selected --source
-python3 ./.pactile/scripts/task.py list-context <task>
-python3 ./.pactile/scripts/task.py validate <task>
-python3 ./.pactile/scripts/get_context.py --mode packages
-```
-
-Confirm the task and JSONL are correct before editing hooks/agents.
+# 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 selected task," "the agent did not read specs," or "there is too much/too little context."
+
+## Read These Files First
+
+1. `.pactile/workflow.md`
+2. `pactile context --mode session --json`
+3. `pactile task selected --source`
+4. Current platform hooks or agent files
+5. The selected task's `implement.jsonl` / `check.jsonl`
+
+## Context Sources
+
+| Source | Purpose |
+| --- | --- |
+| `.pactile/workflow.md` | Workflow and next-action hints. |
+| `.pactile/tasks/<task>/prd.md` | Selected task requirements. |
+| `.pactile/tasks/<task>/design.md` | Complex task technical design. |
+| `.pactile/tasks/<task>/implement.md` | Complex task execution plan. |
+| `.pactile/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
+| `.pactile/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
+| `.pactile/spec/` | Project specs. |
+| `.pactile/workspace/` | Session records. |
+| git status | Current working tree changes. |
+
+## Common Needs And Edit Points
+
+| Need | Edit point |
+| --- | --- |
+| Inject more/less information in new sessions | Project context manifests or the platform session entry. |
+| Change hints on each user input | `[workflow-state:STATUS]` block in `.pactile/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. |
+| Selected task is lost | `pactile task selected --source` and platform session identity propagation. |
+| Change JSONL validation rules | Pactile CLI Node implementation (product change). |
+
+## JSONL Rules
+
+`implement.jsonl` / `check.jsonl` are the key context loading interface:
+
+```jsonl
+{"file": ".pactile/spec/backend/index.md", "reason": "Backend conventions"}
+{"file": ".pactile/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, curate the project context manifests and the platform session entry. Changes to the compiler itself belong in the Pactile product source.
+
+Context cannot grow without bound. Prefer injecting indexes and paths so the AI can read detailed files on demand.
+
+## Change Sub-Agent Context
+
+For Pi Agent workers, determine which context loading mode the integration uses:
+
+- hook push: edit the `inject-subagent-context` hook.
+- agent pull: edit the read steps in the corresponding `pactile-implement` / `pactile-check` agent file.
+
+In both modes, make sure the agent ultimately reads:
+
+1. selected task
+2. the corresponding JSONL
+3. spec/research referenced by the JSONL
+4. `prd.md`
+5. `design.md` if present
+6. `implement.md` if present
+
+## Troubleshooting Order
+
+```bash
+pactile task selected --source
+pactile task list-context <task>
+pactile task validate <task>
+pactile context --mode packages
+```
+
+Confirm the task and JSONL are correct before editing hooks/agents.

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

@@ -1,57 +1,5 @@
-# Change Local Hooks
-
-Hooks are the automation layer that connects a platform to Pactile. 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: `.cursor/hooks.json`
-2. Target platform hooks directory
-3. `.pactile/scripts/common/active_task.py`
-4. `.pactile/scripts/common/session_context.py`
-5. `.pactile/workflow.md`
-
-## Common Hook Types
-
-| Hook | Purpose |
-| --- | --- |
-| session-start | Injects a Pactile 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 `.pactile/scripts/`.
-4. Modify hook behavior.
-5. If the hook depends on workflow content, synchronize `.pactile/workflow.md`.
-
-## Example: Change New-Session Injection Content
-
-First find the session-start hook:
-
-```text
-.cursor/hooks.json
-.cursor/hooks/session-start.py
-```
-
-If the hook ultimately calls `.pactile/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 ./.pactile/scripts/task.py selected --source
-python3 ./.pactile/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.
-- Cursor's hook event surface has changed between releases; confirm against the current Cursor build before wiring a new event.
-- Hooks should read project-local `.pactile/`; they should not depend on Pactile upstream source paths.
-- Hook failures should produce visible errors so AI does not silently lose context.
+# Change hooks
+
+Inspect actual project configuration and host readiness first. A hook file or declaration is not evidence that an event fired. Change only an owned, validated native binding and verify the resulting behavior in a test session.
+
+Keep personal host settings and credentials outside Pactile templates. Add hook registrations only when the active host integration explicitly supports them.