@blxzer/pactile 0.5.0

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/spec-system.md

@@ -0,0 +1,102 @@
+# Local Spec System
+
+`.pactile/spec/` is the user's project-specific engineering spec library. Pactile is not about making AI memorize conventions; it injects relevant specs or requires the AI to read them at the right time.
+
+## Directory Model
+
+A common single-repository structure:
+
+```text
+.pactile/spec/
+├── backend/
+│   ├── index.md
+│   └── ...
+├── frontend/
+│   ├── index.md
+│   └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+A common monorepo structure:
+
+```text
+.pactile/spec/
+├── cli/
+│   ├── backend/
+│   │   ├── index.md
+│   │   └── ...
+│   └── unit-test/
+│       ├── index.md
+│       └── ...
+├── docs-site/
+│   └── docs/
+│       ├── index.md
+│       └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+`index.md` is the entry point for each layer. It should list the Pre-Development Checklist and Quality Check. Specific guidelines live in other Markdown files in the same directory.
+
+## Package Configuration
+
+`.pactile/config.yaml` can declare packages:
+
+```yaml
+packages:
+  cli:
+    path: packages/cli
+  docs-site:
+    path: docs-site
+    type: submodule
+default_package: cli
+```
+
+The AI can run:
+
+```bash
+python3 ./.pactile/scripts/get_context.py --mode packages
+```
+
+This command lists packages and spec layers for the current project. Use this output as the reference when configuring context JSONL.
+
+## How Specs Enter Tasks
+
+Before a task enters implementation, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
+
+```jsonl
+{"file": ".pactile/spec/cli/backend/index.md", "reason": "CLI backend conventions"}
+{"file": ".pactile/spec/cli/unit-test/conventions.md", "reason": "Test expectations"}
+```
+
+Sub-agents or platform preludes read these JSONL files and load the referenced specs. On platforms without sub-agent support, the AI should read the relevant specs directly according to the workflow.
+
+## What Specs Should Contain
+
+Specs should contain executable engineering conventions for the project, not generic best practices:
+
+- Where files should live.
+- How error handling should be expressed.
+- Input/output contracts for APIs, hooks, and commands.
+- Patterns that are forbidden.
+- Cases that require tests.
+- Project-specific pitfalls and how to avoid them.
+
+When the AI learns a new rule during implementation or debugging, it should update `.pactile/spec/` rather than only summarizing it in chat.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Add a new spec layer | `.pactile/spec/<package>/<layer>/index.md` and corresponding guideline files. |
+| Change monorepo spec mapping | `packages` / `default_package` / `spec_scope` in `.pactile/config.yaml`. |
+| Change which specs AI reads before implementation | The task's `implement.jsonl`. |
+| Change which specs AI reads during checking | The task's `check.jsonl`. |
+| Change when specs should be updated | Phase 3.3 in `.pactile/workflow.md` and the `pactile-update-spec` skill. |
+
+## Boundaries
+
+`.pactile/spec/` is the user's project specification, not a permanent copy of Pactile built-in templates. The AI should encourage the user to update it according to the actual project code instead of treating Pactile default templates as immutable documents.

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/task-system.md

@@ -0,0 +1,133 @@
+# Local Task System
+
+The Pactile task system is stored entirely under `.pactile/tasks/` in the user project. Each task is a directory containing requirements, context, research, state, and relationship information.
+
+## Task Directory Structure
+
+```text
+.pactile/tasks/
+├── 04-28-example-task/
+│   ├── task.json
+│   ├── prd.md
+│   ├── design.md
+│   ├── implement.md
+│   ├── implement.jsonl
+│   ├── check.jsonl
+│   └── research/
+└── archive/
+    └── 2026-04/
+```
+
+| File | Purpose |
+| --- | --- |
+| `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
+| `prd.md` | Requirements, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
+| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
+| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
+| `implement.jsonl` | List of spec/research files the implement agent must read first. |
+| `check.jsonl` | List of spec/research files the check agent must read first. |
+| `research/` | Research artifacts. Complex findings should not live only in chat. |
+
+## `task.json`
+
+`task.json` records task status and metadata. Common fields:
+
+| Field | Meaning |
+| --- | --- |
+| `id` / `name` / `title` | Task identity and title. |
+| `status` | Status such as `planning`, `in_progress`, `review`, or `completed`. |
+| `priority` | `P0`, `P1`, `P2`, `P3`. |
+| `creator` / `assignee` | Creator and assignee. |
+| `package` | Target package in a monorepo; may be empty. |
+| `branch` / `base_branch` | Working branch and PR target branch. |
+| `children` / `parent` | Parent/child task relationships. |
+| `commit` / `pr_url` | Commit and PR information after completion. |
+| `meta` | Extension fields. |
+
+## Parent / Child Task Trees
+
+Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
+
+Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
+
+- Source requirements and user-facing scope.
+- The map of child tasks and their responsibility boundaries.
+- Cross-child acceptance criteria and final integration review.
+
+Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
+
+Create new children with:
+
+```bash
+python3 ./.pactile/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
+```
+
+Link or unlink existing tasks with:
+
+```bash
+python3 ./.pactile/scripts/task.py add-subtask <parent-dir> <child-dir>
+python3 ./.pactile/scripts/task.py remove-subtask <parent-dir> <child-dir>
+```
+
+`children` on the parent is a historical list. When a child is archived, Pactile keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
+
+The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
+
+## Selected Task
+
+The user sees a "selected task," and Pactile stores that selection per live session.
+
+```text
+.pactile/.runtime/sessions/<context-key>.json
+```
+
+`task.py select <task>` writes the task path into the runtime session file for the current session. `task.py selected --source` shows the selected task and where it came from. Different AI windows can point to different tasks without overwriting each other.
+
+If the platform or shell environment has no stable session identity, `task.py select` may be unable to set the selected task. The AI should read the error, inspect the platform hook/session environment, and not fall back to a shared global pointer.
+
+## JSONL Context
+
+`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
+
+Format:
+
+```jsonl
+{"file": ".pactile/spec/cli/backend/index.md", "reason": "Backend conventions"}
+{"file": ".pactile/tasks/04-28-example/research/api.md", "reason": "API research"}
+```
+
+Rules:
+
+- Include spec and research files.
+- Do not include code files that are about to be modified.
+- Do not treat temporary conclusions in chat as the only context.
+- Seed rows have no `file` field; they only prompt the AI to fill in real entries.
+
+## Common Commands
+
+```bash
+python3 ./.pactile/scripts/task.py create "<title>" --slug <slug>
+python3 ./.pactile/scripts/task.py dashboard
+python3 ./.pactile/scripts/task.py select <task>
+python3 ./.pactile/scripts/task.py selected --source
+python3 ./.pactile/scripts/task.py start-execution <task> --check
+python3 ./.pactile/scripts/task.py start-execution <task> --approved
+python3 ./.pactile/scripts/task.py add-context <task> implement <file> <reason>
+python3 ./.pactile/scripts/task.py validate <task>
+python3 ./.pactile/scripts/task.py exit
+python3 ./.pactile/scripts/task.py archive <task>
+```
+
+When modifying the task system, the AI should prefer script commands to maintain structure. Edit JSON/Markdown directly only when scripts do not cover the need.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change the default task template | `.pactile/scripts/common/task_store.py` and task creation instructions. |
+| Change status semantics | `.pactile/workflow.md`, workflow-state hook logic, and task usage conventions. |
+| Add task lifecycle actions | `hooks.after_*` in `.pactile/config.yaml`. |
+| Change context rules | Planning artifact guidance in `.pactile/workflow.md` and related platform agent/hook instructions. |
+| Change archive policy | `.pactile/scripts/common/task_store.py` / `task_utils.py`. |
+
+These are local files in the user project. Do not default to editing Pactile CLI source code unless the user wants to contribute upstream.

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/workflow.md

@@ -0,0 +1,75 @@
+# Local Workflow System
+
+`.pactile/workflow.md` is the Pactile workflow source of truth inside the user project. An AI does not need Pactile source code to understand how the current project should move tasks forward; this file is enough.
+
+## File Responsibilities
+
+`.pactile/workflow.md` has three responsibilities:
+
+1. **Explain workflow phases**: Plan, Execute, Finish.
+2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
+3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
+
+## Current Phase Model
+
+```text
+Phase 1: Plan    -> clarify what to build, produce prd.md and required research
+Phase 2: Execute -> implement against the PRD and specs, then check
+Phase 3: Finish  -> final verification, preserve lessons, and wrap up
+```
+
+Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
+
+## Skill Routing
+
+`workflow.md` separates routing by platform capability:
+
+- Platforms with sub-agent support: dispatch `pactile-implement` by default for implementation and `pactile-check` for checking.
+- Platforms without sub-agent support: the main session reads skills such as `pactile-before-dev`, then executes directly.
+
+When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
+
+## Workflow-State Prompt Blocks
+
+The bottom of `workflow.md` can contain state blocks like this:
+
+```text
+[workflow-state:no_task]
+...
+[/workflow-state:no_task]
+```
+
+Hooks choose the right block based on selected task status and inject it into the conversation. Common states include:
+
+| State | Meaning |
+| --- | --- |
+| `no_task` | The current session has no selected task. |
+| `planning` | The task is still in requirements, research, or context configuration. |
+| `in_progress` | The task has entered implementation and checking. |
+| `completed` | The task is complete and waiting for wrap-up or archive. |
+
+If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
+
+## Local Modification Patterns
+
+Common changes:
+
+| Goal | Edit point |
+| --- | --- |
+| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
+| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
+| Change the default implementation/check path | Update Phase 2 and skill routing. |
+| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
+| Change platform differences | Update routing descriptions grouped by platform. |
+
+After editing, make the AI reread `.pactile/workflow.md`; do not assume the flow from the old conversation is still valid.
+
+## Relationship To Platform Files
+
+`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
+
+- skills, such as `pactile-brainstorm` and `pactile-check`.
+- commands/prompts/workflows, such as continue and finish-work.
+- hooks, such as session-start or workflow-state injection.
+
+If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/workspace-memory.md

@@ -0,0 +1,71 @@
+# Local Workspace Memory System
+
+`.pactile/workspace/` stores cross-session memory. Its purpose is to let AI and humans understand what happened before across different windows and different days.
+
+## Directory Structure
+
+```text
+.pactile/workspace/
+├── index.md
+└── <developer>/
+    ├── index.md
+    ├── journal-1.md
+    └── journal-2.md
+```
+
+| File | Purpose |
+| --- | --- |
+| `.pactile/.developer` | Current developer identity. |
+| `.pactile/workspace/index.md` | Global workspace overview. |
+| `.pactile/workspace/<developer>/index.md` | Session index for a developer. |
+| `.pactile/workspace/<developer>/journal-N.md` | Session journal. |
+
+## Developer Identity
+
+Run this the first time:
+
+```bash
+python3 ./.pactile/scripts/init_developer.py <name>
+```
+
+This creates `.pactile/.developer` and the corresponding workspace directory. The AI should not change developer identity casually; if the identity is wrong, first confirm who is using the current project.
+
+## Journal
+
+`journal-N.md` records completed or partially completed work from each session. By default, each journal holds about 2000 lines; after that it rotates to the next file.
+
+Common command for recording a session:
+
+```bash
+python3 ./.pactile/scripts/add_session.py \
+  --title "Session title" \
+  --summary "What changed" \
+  --commit "abc1234"
+```
+
+Planning or review work without a commit can also be recorded by using `--no-commit` or an empty commit value.
+
+## Relationship Between Workspace Memory And Tasks
+
+| System | What it stores |
+| --- | --- |
+| `.pactile/tasks/` | Requirements, design, research, and state for a specific task. |
+| `.pactile/workspace/` | Work records across tasks and sessions. |
+| `.pactile/spec/` | Engineering knowledge preserved as long-term conventions. |
+
+If information is only useful for the selected task, put it in the task directory.
+If information describes what happened in the current session, put it in the workspace journal.
+If information should be followed every time code is written in the future, put it in spec.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change maximum journal lines | `max_journal_lines` in `.pactile/config.yaml`. |
+| Change session auto-commit message | `session_commit_message` in `.pactile/config.yaml`. |
+| Change session content format | `.pactile/scripts/add_session.py`. |
+| Change how workspace is displayed in context | `.pactile/scripts/common/session_context.py`. |
+
+## AI Usage Rules
+
+The AI should not treat workspace as the only source of truth. When resuming a task, read the selected task first, then use workspace for background. After a task is complete, record important process notes in workspace; if long-term rules emerged, update spec.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/agents.md

@@ -0,0 +1,69 @@
+# Agents
+
+Pactile agent files define specialized roles. Common Pactile agents in a user project are:
+
+- `pactile-research`
+- `pactile-implement`
+- `pactile-check`
+
+Responsibility boundaries should stay consistent regardless of file format.
+
+> Pactile previously shipped agent files in per-platform directories for many AI tools (`.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, etc.). The project has converged on **Cursor-only**. New agent definitions ship into `.cursor/agents/`; legacy agent directories in upgraded projects are preserved but not extended.
+
+## Agent Responsibilities
+
+| Agent | Responsibility |
+| --- | --- |
+| `pactile-research` | Investigate the question and write findings into the selected task's `research/`. |
+| `pactile-implement` | Implement against `prd.md`, optional `design.md` / `implement.md`, `implement.jsonl`, and related spec/research. |
+| `pactile-check` | Review changes, fix discovered issues, and run necessary checks. |
+
+Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported.
+
+## Common Paths (Cursor)
+
+| Platform | Agent path |
+| --- | --- |
+| Cursor | `.cursor/agents/pactile-*.md` |
+
+Agent files are dispatched via the Cursor Task tool, opened as Agent sessions, or invoked inline as Skill forms depending on the entry point. See `cursor-subagent-policy.md.txt` for the full entry-point matrix and Method 1–2.6 model dispatch strategy.
+
+## Two Context Loading Modes
+
+### hook push
+
+The Cursor hook (`inject-subagent-context.py`, registered in `.cursor/hooks.json`) injects task context before the agent starts. The agent file itself can focus more on responsibilities and boundaries.
+
+### agent pull
+
+The agent file instructs the agent to read after startup:
+
+- `python3 ./.pactile/scripts/task.py selected --source`
+- `implement.jsonl` or `check.jsonl`
+- spec/research files referenced by JSONL
+- selected task `prd.md`
+- `design.md` if present
+- `implement.md` if present
+
+This mode fits cases where the hook cannot reliably rewrite the sub-agent prompt or the entry point is an Agent session that bypasses the Task hook path.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Implement agent must follow extra restrictions | `.cursor/agents/pactile-implement.md`. |
+| Check agent must run project-specific commands | `.cursor/agents/pactile-check.md`, and `.pactile/spec/` if needed. |
+| Research agent must output a fixed format | `.cursor/agents/pactile-research.md`. |
+| Agent cannot read task context | Agent prelude in the agent file, or the `inject-subagent-context` hook registration in `.cursor/hooks.json`. |
+| Add a project-specific agent | `.cursor/agents/` + related skill/command entry point that invokes it. |
+
+## Modification Principles
+
+1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent.
+2. **Specify the read order**. Agents must know to start from the selected task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present.
+3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues.
+4. **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.
+
+## Do Not Default To Editing Upstream Templates
+
+Local AI should default to modifying agent files inside the user project's `.cursor/agents/`. Discuss upstream template source (`packages/cli/src/templates/cursor/agents/`) only when the user explicitly wants to contribute the change back to Pactile.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/hooks-and-settings.md

@@ -0,0 +1,59 @@
+# Hooks And Settings
+
+Hooks/settings are the entry layer that connects Cursor to Pactile. They decide which scripts run on which Cursor events.
+
+## Settings Responsibilities
+
+`.cursor/hooks.json` registers:
+
+- session-start hook: injects a Pactile overview when a new session starts or context resets (note the Cursor `additional_context` bug #158452 — see `.pactile/framework/cursor-context-injection-guide.md`).
+- workflow-state hook: parses `[workflow-state:STATUS]` blocks from `.pactile/workflow.md` and emits the body matching the selected task `status` on each user input. Parser-only; the script does not embed fallback content.
+- sub-agent context hook: injects task context when implementation/check/research agents start.
+- shell/session bridge: lets shell commands see the same Pactile session identity.
+
+> Pactile previously shipped settings/config files for many platforms (`.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, etc.). The project has converged on **Cursor-only**. New Pactile features ship into `.cursor/hooks.json` + `.cursor/hooks/`.
+
+Whether legacy settings/config files exist in a project depends on which historical `pactile init --<platform>` flags the user previously ran; `pactile update` preserves them.
+
+| Platform | settings/config |
+| --- | --- |
+| Cursor | `.cursor/hooks.json` |
+
+## Hook Script Types
+
+| Script | Purpose |
+| --- | --- |
+| `session-start.py` | Generates session-start context. |
+| `inject-workflow-state.py` | Parses `[workflow-state:STATUS]` blocks in `.pactile/workflow.md` and emits the body matching the selected task status. Falls back to `Refer to workflow.md for current step.` when no matching block exists. |
+| `inject-subagent-context.py` | Injects PRD, JSONL context, and related spec/research into sub-agents. |
+| `inject-shell-session-context.py` | Lets shell commands inherit Pactile session identity. |
+| `rename-session-for-task.py` | After successful `task.py select` / `start-execution --approved`, prompts main-session rename to task directory name (best-effort `rename_chat`). |
+
+Cursor exposes sessionStart, preToolUse on Task/Subagent, beforeShellExecution, afterShellExecution, and stop events. Confirm against the current Cursor release before wiring a new event name; the available event surface has evolved over time and historical platform documentation may be stale.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| AI should see more/less context in a new session | `.cursor/hooks.json` → `session-start` hook (or `.cursor/rules/*.mdc` for content the model must see every turn — see `.pactile/framework/cursor-context-injection-guide.md`). |
+| Per-turn hint policy should change | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The hook parses workflow.md verbatim — no script edit required. |
+| Sub-agent cannot read PRD/spec | `inject-subagent-context.py` hook or agent prelude in `.cursor/agents/*.md`. |
+| `task.py selected` in shell has no selected task | `inject-shell-session-context.py` hook or environment-variable configuration. |
+| Disable an automatic injection | The corresponding hook registration in `.cursor/hooks.json`. |
+
+## Modification Principles
+
+1. **Settings wire things up; hooks define behavior**. If only the hook changes, Cursor may never call it. If only settings change, behavior may not change.
+2. **Confirm Cursor event names first**. Cursor's hook event surface has changed between releases; what an older guide calls `UserPromptSubmit` may now be modeled by `beforeSubmitPrompt` instead.
+3. **Hooks read local `.pactile/`, not upstream source**. `.pactile/scripts/` and `.pactile/workflow.md` in the user project are the default targets.
+4. **Errors must be visible**. Hook failures should tell the user what was not injected instead of silently leaving the AI without context.
+
+## Troubleshooting Path
+
+If the user says "AI did not read Pactile state":
+
+1. Check whether `.cursor/hooks.json` registers the hook.
+2. Check whether the hook file exists under `.cursor/hooks/`.
+3. Manually run the `.pactile/scripts/get_context.py` or `task.py selected --source` command that the hook depends on.
+4. Check whether selected task state exists in `.pactile/.runtime/sessions/`.
+5. Check whether the Cursor shell passes session identity.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/overview.md

@@ -0,0 +1,45 @@
+# Platform Files Overview
+
+Pactile connects the same local architecture to **Cursor**. `.pactile/` stores the shared runtime; `.cursor/` stores adapter files that define how Cursor enters Pactile.
+
+When a local AI modifies Pactile, it should distinguish two file categories first:
+
+- **Shared files**: `.pactile/workflow.md`, `.pactile/tasks/`, `.pactile/spec/`, `.pactile/scripts/`.
+- **Platform files**: `.cursor/` (settings, hooks, agents, skills, commands, rules).
+
+Platform files do not store business state. They let Cursor read Pactile state, call Pactile scripts, and load Pactile skills/agents/hooks.
+
+> **Historical note**: Pactile previously shipped adapter directories for many AI tools (`.claude/`, `.codex/`, `.opencode/`, etc.). The project has converged on **Cursor-only**. Legacy adapter directories may still exist in upgraded projects (`pactile update` preserves user files), but new framework/runtime behavior targets Cursor exclusively.
+
+## Platform File Categories (Cursor)
+
+| Category | Common paths | Purpose |
+| --- | --- | --- |
+| settings/config | `.cursor/hooks.json` | Register hooks and platform behavior. |
+| hooks | `.cursor/hooks/` | Inject context at session start, pre-tool-use on Task/Subagent, before-shell-execution, and stop events. |
+| rules | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Per-turn policy prepended before every prompt (e.g. Request Triage, retrieval routing). See `.pactile/framework/cursor-context-injection-guide.md` for the channel-reliability matrix. |
+| agents | `.cursor/agents/` | Define `pactile-research`, `pactile-implement`, and `pactile-check` for Task / Agent-session dispatch. |
+| skills | `.cursor/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
+| commands | `.cursor/commands/` | User-invocable `/slash` entry points (e.g. `pactile-continue`, `record-session`). |
+
+## Cursor Integration Mode
+
+Cursor combines three integration styles:
+
+1. **Hook / Extension Driven** — `.cursor/hooks.json` + `.cursor/hooks/` fire on sessionStart, pre-tool-use on Task/Subagent, beforeShellExecution, and stop. Common capabilities: session-start Task Dashboard + Phase Index injection (note the `additional_context` Cursor bug #158452 — use `.cursor/rules` or `AGENTS.md` for must-always-be-visible content), PRD/jsonl injection when sub-agents start, shell commands inheriting session identity.
+2. **Agent Prelude / Pull-Based** — `.cursor/agents/*.md` instruct each custom Task subagent to read the selected task, PRD, and JSONL context after startup (the `<!-- pactile-hook-injected -->` marker confirms injected context).
+3. **Main-Session Workflow** — `.cursor/commands/*.md` and `.cursor/skills/*.md` guide the main-session AI to read files, run scripts, and move tasks forward; `.cursor/rules/*.mdc` enforce per-turn policy.
+
+To change "when the AI knows what," inspect `.cursor/hooks.json` and `.cursor/rules/` first. To change how sub-agents load context, inspect `.cursor/agents/`. To change user-invocable entry points, inspect `.cursor/commands/` and `.cursor/skills/`.
+
+## Local Modification Order
+
+When the user asks to customize behavior:
+
+1. Read `.pactile/workflow.md` to confirm the shared flow.
+2. Read `.cursor/hooks.json` to see which hooks are registered.
+3. Read the relevant `.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md`, `.cursor/commands/*.md`, and `.cursor/rules/*.mdc`.
+4. Modify the local file closest to the user's need.
+5. If the change affects the shared flow, synchronize `.pactile/workflow.md` or `.pactile/spec/`.
+
+Do not modify only platform files and forget the shared workflow. Do not modify only `.pactile/workflow.md` and forget that platform entry points may still contain old descriptions.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/platform-map.md

@@ -0,0 +1,45 @@
+# Platform File Map
+
+This page lists Pactile file locations in a user project on **Cursor**.
+
+Pactile originally supported multiple AI platforms (Claude Code, Codex, OpenCode, Kilo, Kiro, Gemini, Antigravity, Windsurf, Qoder, CodeBuddy, GitHub Copilot, Factory Droid, Pi Agent). The project has since converged on **Cursor-only**. Legacy adapter directories may still exist in upgraded projects (`pactile update` preserves user files), but new framework/runtime behavior targets Cursor exclusively.
+
+## Matrix
+
+| Platform | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
+| --- | --- | --- | --- | --- | --- |
+| Cursor | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
+
+## Capability Reference (Cursor)
+
+- **Skills** auto-trigger via the workflow matcher and can be read on demand. They live in `.cursor/skills/`.
+- **Agents** (`pactile-research`, `pactile-implement`, `pactile-check`) live in `.cursor/agents/` and are dispatched via the Task tool or opened as Agent sessions / Skill forms depending on the entry point (see `cursor-subagent-policy.md.txt`).
+- **Commands** (e.g. `record-session`, `pactile-continue`) live in `.cursor/commands/` and are user-invocable via `/slash`.
+- **Hooks** (session start, pre-tool-use on Task/Subagent, before-shell-execution, stop) are registered in `.cursor/hooks.json` and their handler scripts live in `.cursor/hooks/`.
+- **Project rules** (always-applied policy) live in `.cursor/rules/*.mdc`.
+
+## Decision Rules When Modifying Platform Files
+
+1. User specified a platform other than Cursor: treat as a legacy adapter inspection — preserve existing files but do not extend new behavior there.
+2. User says "all platforms should do this": in Cursor-only world this is equivalent to "modify the Cursor path"; also mirror any dogfooded copy under `.cursor/` in `packages/cli/src/templates/cursor/` if applicable.
+3. User only says "my AI": inspect which directories actually exist in the project; on a fresh `pactile init` only `.cursor/` and `.pactile/` are created.
+4. User wants project rules: prefer `.pactile/spec/` or a project-local skill under `.cursor/skills/`.
+5. User wants Pactile behavior: edit `.pactile/workflow.md` plus `.cursor/hooks.json` / `.cursor/agents/` / `.cursor/skills/` / `.cursor/commands/`.
+
+## When Paths Differ
+
+Cursor's layout can change between versions, and user projects may already be customized. If this table disagrees with local files, use the actual settings/config in the user project as authoritative:
+
+- Check the hook that `.cursor/hooks.json` registers.
+- Check the script that a command/agent points to.
+- Judge behavior by the read rules currently written in the agent file.
+
+Do not delete a custom file just because it is not listed in this path table.
+
+## Legacy Adapter Handling
+
+If a user project still contains legacy platform directories (e.g. `.claude/`, `.codex/`, `.opencode/`):
+
+- `pactile update` preserves them; do not delete on sight.
+- If the user asks to clean them up, suggest removing the unused platform directories after confirming they are not shared with another tool.
+- Do not register new hooks/agents/skills/commands under legacy platform directories. New Pactile features ship to `.cursor/` only.