@blxzer/pactile 0.5.0 → 0.6.0-beta.2

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

@@ -1,117 +1,117 @@
----
-name: pactile-handoff
-description: "Condense the current session into a portable handoff document so a new agent / harness / directory can continue the work. User-invoked when the work needs to 'travel' (switch harness, switch directory or repo, hand to a colleague, or fork a side branch); writes to the OS temp directory and reports the full path."
-argument-hint: "What will the next session use this for?"
-disable-model-invocation: true
----
-
-# pactile-handoff — Session handoff
-
-Condense the current session into a **portable** handoff document (`pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md`), written to the **OS temp directory** (does not pollute the workspace), so a new agent can continue without the original session. User-invoked (`disable-model-invocation: true` — the agent never triggers it on its own; it is written only when the user invokes `/pactile-handoff`).
-
----
-
-## How this differs from a task `handoff.md` (read first)
-
-**The two have opposite purposes — not interchangeable:**
-
-| | This skill (session handoff) | Task `handoff.md` |
-| --- | --- | --- |
-| What | Portable cross-session summary | Child-task integration / implementation-window **delivery evidence** |
-| Where | OS temp directory (volatile) | `.pactile/tasks/<task>/` (durable, archived with the task) |
-| Lifecycle | Single transfer; dead once the work lands | Kept with the task evidence for Parent / review traces |
-
-A task directory's `handoff.md` is the evidence file for `integrate-child` / `review-child`, **not** a session handoff document; the temp file this skill produces is **not** task evidence.
-
-## When to use / when not (five-question tree)
-
-At stage boundaries first ask: **does the work still continue in this session?**
-
-1. **Continue** — default preference: keep going in this session
-2. **Clear** — context can be dropped; clear and restart
-3. **Handoff** — the work needs to travel → this skill
-4. **Subagent** — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
-5. **Compact** — same harness, same directory, only intent compression needed → use the platform compact
-
-**Handoff only when the work needs to travel**, triggered by exactly four situations:
-
-| Situation | Why a file is needed |
-| --- | --- |
-| Switch harness (e.g. Cursor → Codex) | The new harness cannot see the old context |
-| Switch directory / repo | Common for prototype directories and new repos |
-| Hand to a colleague | They need something they can read independently |
-| Fork a side branch (main line continues) | You stay in this session; a second agent takes a copy in parallel |
-
-**Same harness, same directory continuation → compact / continue, not handoff.** The value of handoff is **portability**, not better compression; if only intent compression is wanted, `/compact` is the better fit.
-
-## Steps
-
-1. **Read the user argument**: the "next-session purpose" passed on invocation decides which whys to keep (trim key decision rationale by purpose — do not take everything verbatim).
-2. **Write the temp file** (path rules below).
-3. **Report the full absolute path** (required): temp paths are long and differ per OS; the user must get the path first.
-4. **Remind about volatility**: the temp file may be cleaned by the environment (Codex clears temp across sessions; `/private/tmp` is lost on reboot). For cross-hour / cross-harness continuation, ask the user to copy it to a durable location immediately (this also applies to other temp files referenced by the document).
-
-### Path rules (Windows first)
-
-```text
-$env:TEMP\pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md
-```
-
-- Windows: `$env:TEMP` (i.e. `%TEMP%`), e.g. `C:\Users\<user>\AppData\Local\Temp\pactile-handoff-20260808-153000-migrate-ts.md`
-- Linux / macOS: `$TMPDIR/pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md` (`/tmp` when `$TMPDIR` is unset)
-- After writing, always report the **full absolute path** to the user (Write-Host or plain text) — never just the filename.
-
-## Content template (English skeleton)
-
-> Follow `artifact_locale` when the project uses it; English by default.
-
-```markdown
-# Session handoff — <work summary>
-
-> Generated by pactile-handoff at <time> · Next-session purpose: <user argument>
-
-## Goal
-<what the in-flight work is trying to achieve>
-
-## Done
-- <items>
-
-## Not done / Blocked
-- <items>
-
-## Next steps
-1. <ordered steps>
-
-## Key whys (trimmed by next-session purpose)
-- <decision + reason; whys unrelated to this purpose can be omitted>
-
-## Facts vs unverified beliefs
-- Facts: <verified>
-- Beliefs (unverified): <assumptions — never write them as facts>
-
-## Pointers (reference paths only, never copy bodies)
-- Task: `.pactile/tasks/<task>/` (prd.md / design.md / implement.md / verify.md)
-- Context: `CONTEXT.md` · Research: `<task>/research/`
-- Prototype evidence (if a prototype was involved): `<task>/research/prototype-<slug>.py` (see `.pactile/spec/guides/prototype-guide.md` §9)
-- Other: ADR / issue / commit / diff paths or URLs
-
-## Suggested skills (for the continuing agent)
-- <skill name list, e.g. pactile-brainstorm, pactile-check, pactile-continue>
-```
-
-## Rules
-
-- **Reference, don't copy**: anything already on disk (spec / PRD / ADR / issue / commit / diff) gets a path or URL only, never pasted verbatim. The document should be a small part of the session; a path list replaces copying.
-- **Redact**: API keys, tokens, passwords, PII → replace with `<REDACTED>` before writing; when unsure, write `<REDACTED>`.
-- **Facts vs beliefs**: unverified assumptions must be marked, never written as verified facts — the continuing agent will treat the document as a contract and will not re-check.
-- **Prototype evidence pointer**: when the session involved a prototype, list the prototype evidence path in the pointers section (`prototype-guide.md` §9: git throwaway branch or a task `research/` path snapshot) and confirm the evidence is captured before cleanup.
-- **Delivery**: have the new agent **read the file path**; do not stuff the summary into shell quotes to launch the new agent (backticks / `$(...)` get swallowed and silently truncated).
-
-## Anti-patterns
-
-- ❌ Treating handoff as a long-lived document: it is a transit document for a single transfer and dies once the work lands (long-term facts belong in `AGENTS.md` / spec, not handoff)
-- ❌ Pasting large spec / PRD / diff bodies (should reference paths only)
-- ❌ Stuffing the summary into shell quotes to launch the next agent (silent truncation risk)
-- ❌ Not reporting the full path / not reminding about temp volatility
-- ❌ Writing a handoff for same-harness same-directory continuation (should compact / continue)
-- ❌ Writing keys / tokens into the document
+---
+name: pactile-handoff
+description: "Condense the current session into a portable handoff document so a new agent / harness / directory can continue the work. User-invoked when the work needs to 'travel' (switch harness, switch directory or repo, hand to a colleague, or fork a side branch); writes to the OS temp directory and reports the full path."
+argument-hint: "What will the next session use this for?"
+disable-model-invocation: true
+---
+
+# pactile-handoff — Session handoff
+
+Condense the current session into a **portable** handoff document (`pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md`), written to the **OS temp directory** (does not pollute the workspace), so a new agent can continue without the original session. User-invoked (`disable-model-invocation: true` — the agent never triggers it on its own; it is written only when the user invokes `/pactile-handoff`).
+
+---
+
+## How this differs from a task `handoff.md` (read first)
+
+**The two have opposite purposes — not interchangeable:**
+
+| | This skill (session handoff) | Task `handoff.md` |
+| --- | --- | --- |
+| What | Portable cross-session summary | Child-task integration / implementation-window **delivery evidence** |
+| Where | OS temp directory (volatile) | `.pactile/tasks/<task>/` (durable, archived with the task) |
+| Lifecycle | Single transfer; dead once the work lands | Kept with the task evidence for Parent / review traces |
+
+A task directory's `handoff.md` is the evidence file for `integrate-child` / `review-child`, **not** a session handoff document; the temp file this skill produces is **not** task evidence.
+
+## When to use / when not (five-question tree)
+
+At stage boundaries first ask: **does the work still continue in this session?**
+
+1. **Continue** — default preference: keep going in this session
+2. **Clear** — context can be dropped; clear and restart
+3. **Handoff** — the work needs to travel → this skill
+4. **Subagent** — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
+5. **Compact** — same harness, same directory, only intent compression needed → use the platform compact
+
+**Handoff only when the work needs to travel**, triggered by exactly four situations:
+
+| Situation | Why a file is needed |
+| --- | --- |
+| Switch tasks or hosts | The destination may not see the previous context |
+| Switch directory / repo | Common for prototype directories and new repos |
+| Hand to a colleague | They need something they can read independently |
+| Fork a side branch (main line continues) | You stay in this session; a second agent takes a copy in parallel |
+
+**Same harness, same directory continuation → compact / continue, not handoff.** The value of handoff is **portability**, not better compression; if only intent compression is wanted, `/compact` is the better fit.
+
+## Steps
+
+1. **Read the user argument**: the "next-session purpose" passed on invocation decides which whys to keep (trim key decision rationale by purpose — do not take everything verbatim).
+2. **Write the temp file** (path rules below).
+3. **Report the full absolute path** (required): temp paths are long and differ per OS; the user must get the path first.
+4. **Remind about volatility**: the temp file may be cleaned by the environment (Codex clears temp across sessions; `/private/tmp` is lost on reboot). For cross-hour / cross-harness continuation, ask the user to copy it to a durable location immediately (this also applies to other temp files referenced by the document).
+
+### Path rules (Windows first)
+
+```text
+$env:TEMP\pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md
+```
+
+- Windows: `$env:TEMP` (i.e. `%TEMP%`), e.g. `C:\Users\<user>\AppData\Local\Temp\pactile-handoff-20260808-153000-migrate-ts.md`
+- Linux / macOS: `$TMPDIR/pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md` (`/tmp` when `$TMPDIR` is unset)
+- After writing, always report the **full absolute path** to the user (Write-Host or plain text) — never just the filename.
+
+## Content template (English skeleton)
+
+> Follow `artifact_locale` when the project uses it; English by default.
+
+```markdown
+# Session handoff — <work summary>
+
+> Generated by pactile-handoff at <time> · Next-session purpose: <user argument>
+
+## Goal
+<what the in-flight work is trying to achieve>
+
+## Done
+- <items>
+
+## Not done / Blocked
+- <items>
+
+## Next steps
+1. <ordered steps>
+
+## Key whys (trimmed by next-session purpose)
+- <decision + reason; whys unrelated to this purpose can be omitted>
+
+## Facts vs unverified beliefs
+- Facts: <verified>
+- Beliefs (unverified): <assumptions — never write them as facts>
+
+## Pointers (reference paths only, never copy bodies)
+- Task: `.pactile/tasks/<task>/` (prd.md / design.md / implement.md / verify.md)
+- Context: `CONTEXT.md` · Research: `<task>/research/`
+- Prototype evidence (if a prototype was involved): `<task>/research/prototype-<slug>.mjs` (see `.pactile/spec/guides/prototype-guide.md` §9)
+- Other: ADR / issue / commit / diff paths or URLs
+
+## Suggested skills (for the continuing agent)
+- <skill name list, e.g. pactile-brainstorm, pactile-check, pactile-continue>
+```
+
+## Rules
+
+- **Reference, don't copy**: anything already on disk (spec / PRD / ADR / issue / commit / diff) gets a path or URL only, never pasted verbatim. The document should be a small part of the session; a path list replaces copying.
+- **Redact**: API keys, tokens, passwords, PII → replace with `<REDACTED>` before writing; when unsure, write `<REDACTED>`.
+- **Facts vs beliefs**: unverified assumptions must be marked, never written as verified facts — the continuing agent will treat the document as a contract and will not re-check.
+- **Prototype evidence pointer**: when the session involved a prototype, list the prototype evidence path in the pointers section (`prototype-guide.md` §9: git throwaway branch or a task `research/` path snapshot) and confirm the evidence is captured before cleanup.
+- **Delivery**: have the new agent **read the file path**; do not stuff the summary into shell quotes to launch the new agent (backticks / `$(...)` get swallowed and silently truncated).
+
+## Anti-patterns
+
+- ❌ Treating handoff as a long-lived document: it is a transit document for a single transfer and dies once the work lands (long-term facts belong in `AGENTS.md` / spec, not handoff)
+- ❌ Pasting large spec / PRD / diff bodies (should reference paths only)
+- ❌ Stuffing the summary into shell quotes to launch the next agent (silent truncation risk)
+- ❌ Not reporting the full path / not reminding about temp volatility
+- ❌ Writing a handoff for same-harness same-directory continuation (should compact / continue)
+- ❌ Writing keys / tokens into the document

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.