@blxzer/pactile 0.5.0

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

@@ -0,0 +1,161 @@
+---
+name: pactile-check
+description: "Comprehensive quality verification on two axes — Standards (spec compliance, lint, type-check, tests, code smells, cross-layer data flow) and Spec (prd fidelity, scope, learning/spec-sync). Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions."
+---
+
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Task Artifacts and Applicable Specs
+
+Read the selected task artifacts in order:
+
+- `prd.md`
+- `design.md` if present
+- `implement.md` if present
+
+```bash
+python ./.pactile/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .pactile/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist (dual-axis)
+
+Report **Standards and Spec in two separate sections** — never merge them into a single severity ranking. Standards findings first, then Spec findings; the same issue may be cross-referenced on both sides, but one axis must not mask the other. Do NOT output a "combined top risks" list mixing spec violations with requirement deviations.
+
+### Dual-axis dispatch (Full+ only)
+
+- **Lite / no task context**: single pass — the main agent runs Standards then Spec sequentially (no parallel split).
+- **Full+ and sub-agents available**: may dispatch two read-only review sub-agents in parallel (a Standards-agent and a Spec-agent). They **only report findings, never modify code**; the main agent consolidates and fixes per Step 6.
+- **Sub-agents unavailable**: degrade to single pass — do not block the check.
+
+### Standards (did we write it right)
+
+#### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+#### Test Coverage (verification strength — not TDD)
+
+Follow `.pactile/framework/verification-strength-guide.md` for **graded** validation depth by closeout profile. pactile does **not** mandate red-green TDD or per-function unit tests.
+
+- [ ] **Lite:** focused validation on touched behavior recorded in `verify.md` (`Validation:` line + result)
+- [ ] **Full:** above + `Check evidence:` + `Reviewed change-set:` when contract requires code-review gate
+- [ ] New function / bug fix → add or update tests **when the project's norms and task scope require it** — not as automatic TDD ceremony
+- [ ] `python ./.pactile/scripts/task.py validate <task>` passing JSONL schema **≠** task acceptance; substantive `verify.md` signals still required
+
+#### Fowler 12 Smells
+
+Scan the change surface against `references/fowler-12-smells.md` (12 named smells, one-line criterion + don't-report boundary each). Report when hit, `N/A` when not — do not pad the report with misses.
+
+#### False-positive calibration (AI cross-review)
+
+Before prioritizing any CRITICAL/WARNING finding, read `.pactile/spec/guides/index.md` → **"When Verifying AI Cross-Review Results"**: verify each finding against the actual code; budget ~35% false-positive rate for AI reviews; typical patterns: trust boundary confusion, ignoring design comments, variable misreading.
+
+### Spec (did we build the right thing)
+
+#### prd / design / implement fidelity
+
+- [ ] Against `prd.md` Goal / Requirements / Acceptance Criteria: is the implementation faithful, and does it stay **within scope** (no over-scope)?
+- [ ] Are `design.md` / `implement.md` boundaries violated (if present)?
+
+#### Durable Learning (Phase 3.3)
+
+- [ ] `verify.md` contains exactly one token: `Learning decision: update-spec` | `no-update` | `unsure`
+- [ ] If `update-spec` or `unsure`: `research/learning-proposal.md` exists (or documented `N/A` with reason) and matches the decision
+- [ ] If `no-update`: includes `no durable learning` (or guide-equivalent) plus brief rationale
+- [ ] If `update-spec`: spec was written only after confirmation; `Spec update evidence:` points at `.pactile/spec/...`
+- [ ] No silent edits to `.pactile/spec/` without confirmation
+
+#### Spec Sync
+
+- [ ] Does `.pactile/spec/` need updates? (route through semi-automatic flow: proposal → confirm → `pactile-update-spec`)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+#### Retrieval evidence (when task used research / smart-search / optional pack)
+
+- [ ] **`verify.md` lists unresolved retrieval gaps** — external facts still unverified, missing `research/` or `research/smart-search/` evidence, or claims without source/Git/test corroboration
+- [ ] If `{TASK}/research/retrieval-pack-latest.json` exists, top `contextPack.selected` items are cited or gaps are explicitly noted in `verify.md`
+
+**Evidence pack (graceful):** Path `{TASK}/research/retrieval-pack-latest.json`. If absent, skip — no error.
+
+When present, Read the pack and ensure `verify.md` has `## Evidence pack reference` citing `contextPack.selected` (`title`, `source`, `reference`, `score`) or explicit gaps. Empty `selected` with existing `research/` → note stale pack or scoring failure in `verify.md`.
+
+#### Terminology / ADR consistency (one line)
+
+- [ ] Read root `CONTEXT.md`: do terms in the change mix `_Avoid_` aliases? If an irreversible decision was introduced, should there be an ADR? (Prompt only — do not force creating a file.)
+
+### Report format
+
+```markdown
+## Standards findings
+- [sev] ...
+
+## Spec findings
+- [sev] ...
+
+## Summary
+- Standards: N issues (not ranked against Spec)
+- Spec: M issues
+```
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report violations found (Standards and Spec sections per Step 4 format) and fix them directly. Parallel review sub-agents **do not fix** — the main agent owns all fixes. Re-run project checks after fixes.

package/dist/templates/common/bundled-skills/pactile-check/references/fowler-12-smells.md

@@ -0,0 +1,28 @@
+# Fowler 12 Smells — Quick Criterion Reference
+
+Scan the change surface line by line: report when a smell is hit, write `N/A` when not. Each criterion is a one-line "is" definition; the **don't-report** boundaries guard against false positives (paired with the ~35% false-positive discipline in `.pactile/spec/guides/index.md`).
+
+1. **Mysterious Name** — a name fails to express the code's intent (what it does / why it exists); the reader must read the implementation to understand it.
+   Don't report: evaluate only within the changed lines; do not opportunistically flag historical naming outside the change surface.
+2. **Duplicated Code** — the same structure/expression is repeated in 2+ places, so a change must be synced across several sites.
+   Don't report: small test boilerplate (e.g. a one-line setup) where extraction would reduce readability.
+3. **Feature Envy** — a method uses another object's data/methods far more than its own.
+   Don't report: an orchestration point that coordinates multiple collaborators is the method's job, not envy.
+4. **Data Clumps** — the same group of fields/parameters keep appearing together and should be bundled into an object.
+   Don't report: don't force types that only bundle without adding behavior (lazy creation discipline).
+5. **Primitive Obsession** — primitives (string/number/bool) carry concepts that deserve their own type (IDs, amounts, states).
+   Don't report: when the value domain is already constrained by an existing validation/config layer and adds no new behavior.
+6. **Repeated Switches** — the same discriminating field (kind/type/status) drives switch/if-else chains repeated in multiple places.
+   Don't report: 1–2 occurrences where that is the language idiom (e.g. ADT pattern matching).
+7. **Shotgun Surgery** — one conceptual change requires synchronized edits scattered across many places.
+   Don't report: when the multiple edits are concentrated in one cohesive module (locality holds).
+8. **Divergent Change** — one module changes frequently for many different reasons.
+   Don't report: when the module is an intentional facade/aggregator.
+9. **Speculative Generality** — abstractions/parameters/hooks are built for imagined future needs with no current caller.
+   Don't report: abstractions actually used in this change.
+10. **Message Chains** — a long call chain `a.b().c().d()` is needed to reach a target value, with intermediate links being pure pass-through.
+    Don't report: when the fluent/builder chain is itself the public interface.
+11. **Middle Man** — a class/method mostly forwards to somewhere else and adds little value of its own.
+    Don't report: when the forwarding provides encapsulation/seam value (e.g. an adapter sitting at a seam).
+12. **Refused Bequest** — a subclass barely uses inherited parent behavior/fields, making the inheritance relationship nominal.
+    Don't report: when inheritance is used only for type identity/interface satisfaction (is-a semantics) or the unused members are minimal.

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

@@ -0,0 +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

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

@@ -0,0 +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.

package/dist/templates/common/bundled-skills/pactile-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 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.

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

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

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

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

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

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