@blxzer/pactile 0.5.0 → 0.6.0-beta.2

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

@@ -1,88 +1,82 @@
-# Change Local Task Lifecycle
-
-Task lifecycle includes creation, selection, execution start, context configuration, archive, parent/child tasks, and lifecycle hooks. The default customization targets are `.pactile/tasks/`, `.pactile/config.yaml`, and `.pactile/scripts/`.
-
-## Read These Files First
-
-1. `.pactile/workflow.md`
-2. `.pactile/config.yaml`
-3. `.pactile/scripts/task.py`
-4. `.pactile/scripts/common/task_store.py`
-5. `.pactile/scripts/common/task_utils.py`
-6. The selected task's `.pactile/tasks/<task>/task.json`
-
-## Common Needs And Edit Points
-
-| Need | Edit point |
-| --- | --- |
-| Automatically sync an external system after task creation | `hooks.after_create` in `.pactile/config.yaml`. |
-| Automatically update status after execution start | `hooks.after_start` in `.pactile/config.yaml`. |
-| Clean external resources after archive | `hooks.after_archive` in `.pactile/config.yaml`. |
-| Change default task fields | `.pactile/scripts/common/task_store.py`. |
-| Change task parsing/search | `.pactile/scripts/common/task_utils.py`. |
-| Change selected task behavior | `.pactile/scripts/common/active_task.py`. |
-
-## lifecycle hooks
-
-`.pactile/config.yaml` supports:
-
-```yaml
-hooks:
-  after_create:
-    - "python3 .pactile/scripts/hooks/my_sync.py create"
-  after_start:
-    - "python3 .pactile/scripts/hooks/my_sync.py start"
-  after_archive:
-    - "python3 .pactile/scripts/hooks/my_sync.py archive"
-```
-
-Hook commands receive the `TASK_JSON_PATH` environment variable, pointing to the task's `task.json`. Hook failures should usually warn, but not block the main task operation.
-
-## Change Task Fields
-
-If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields.
-
-Example:
-
-```json
-"meta": {
-  "linearIssue": "ENG-123",
-  "risk": "high"
-}
-```
-
-If standard fields really need to change, inspect every local script that reads `task.json`.
-
-## Change Selected Task
-
-Selected task is session-level state stored in `.pactile/.runtime/sessions/`. Do not fall back to a global `.current-task` model. If the user wants to change selected task behavior, edit:
-
-- `.pactile/scripts/common/active_task.py`
-- platform hooks or shell session bridges
-- selected task descriptions in `.pactile/workflow.md`
-
-### `task.py create` Does Not Select
-
-`cmd_create` in `.pactile/scripts/common/task_store.py` writes the task directory and planning artifacts only. The behavior:
-
-- The task's `status=planning` is written.
-- No selected-task pointer is written, even when session identity exists.
-- The user or AI selects the task later with `task.py select <dir>` when they explicitly choose to enter it.
-
-This keeps new sessions and bare task creation at `Selected task: none` until a live-session choice is made.
-
-If you fork `task.py` to add a new creation path (e.g. an external import that bypasses `cmd_create`), audit that it does not auto-select or auto-start the created task. The full status writer table is in `.pactile/spec/cli/backend/workflow-state-contract.md`.
-
-## Modification Steps
-
-1. Confirm the selected task with `python3 ./.pactile/scripts/task.py selected --source`.
-2. Read the selected task's `task.json` and confirm status and fields.
-3. For configuration needs, edit `.pactile/config.yaml` first.
-4. For script behavior needs, then edit `.pactile/scripts/`.
-5. If the AI flow changed, synchronize `.pactile/workflow.md`.
-
-## Do Not
-
-- Do not directly edit `.pactile/.runtime/sessions/` to "fix" business state.
-- Do not hard-code project-private fields into scripts; prefer `meta`.
-- Do not default to asking the user to fork Pactile CLI.
+# Change Local Task Lifecycle
+
+Task lifecycle includes creation, selection, execution start, context configuration, archive, parent/child tasks, and lifecycle hooks. Project customization targets are `.pactile/tasks/` and `.pactile/config.yaml`; runtime behavior lives in the Pactile Node CLI.
+
+## Read These Files First
+
+1. `.pactile/workflow.md`
+2. `.pactile/config.yaml`
+3. `pactile task dashboard` and `pactile task selected --source`
+4. The selected task's `.pactile/tasks/<task>/task.json`
+
+## Common Needs And Edit Points
+
+| Need | Edit point |
+| --- | --- |
+| Automatically sync an external system after task creation | `hooks.after_create` in `.pactile/config.yaml`. |
+| Automatically update status after execution start | `hooks.after_start` in `.pactile/config.yaml`. |
+| Clean external resources after archive | `hooks.after_archive` in `.pactile/config.yaml`. |
+| Change default task fields | Pactile CLI Node implementation (product change). |
+| Change task parsing/search | Pactile CLI Node implementation (product change). |
+| Change selected task behavior | Pactile CLI Node implementation and platform session bridge. |
+
+## lifecycle hooks
+
+`.pactile/config.yaml` supports:
+
+```yaml
+hooks:
+  after_create:
+    - "node .pactile/hooks/my-sync.mjs create"
+  after_start:
+    - "node .pactile/hooks/my-sync.mjs start"
+  after_archive:
+    - "node .pactile/hooks/my-sync.mjs archive"
+```
+
+Hook commands receive the `TASK_JSON_PATH` environment variable, pointing to the task's `task.json`. Hook failures should usually warn, but not block the main task operation.
+
+## Change Task Fields
+
+If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields.
+
+Example:
+
+```json
+"meta": {
+  "linearIssue": "ENG-123",
+  "risk": "high"
+}
+```
+
+If standard fields really need to change, update the Pactile CLI implementation and its contract tests.
+
+## Change Selected Task
+
+Selected task is session-level state stored in `.pactile/.runtime/sessions/`. Check `pactile task selected --source` and the platform session bridge when selection is lost. Do not fall back to a global `.current-task` model.
+
+### `pactile task create` Does Not Select
+
+`pactile task create` writes the task directory and planning artifacts only. The behavior:
+
+- The task's `status=planning` is written.
+- No selected-task pointer is written, even when session identity exists.
+- The user or AI selects the task later with `pactile task select <dir>` when they explicitly choose to enter it.
+
+This keeps new sessions and bare task creation at `Selected task: none` until a live-session choice is made.
+
+If you add a new creation path to the Pactile product, verify that it does not auto-select or auto-start the created task.
+
+## Modification Steps
+
+1. Confirm the selected task with `pactile task selected --source`.
+2. Read the selected task's `task.json` and confirm status and fields.
+3. For configuration needs, edit `.pactile/config.yaml` first.
+4. For runtime behavior needs, change the Pactile product source and verify the Node CLI.
+5. If the AI flow changed, synchronize `.pactile/workflow.md`.
+
+## Do Not
+
+- Do not directly edit `.pactile/.runtime/sessions/` to "fix" business state.
+- Do not hard-code project-private fields into scripts; prefer `meta`.
+- Do not default to asking the user to fork Pactile CLI.

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

@@ -1,65 +1,65 @@
-# Change Local Workflow
-
-When the user wants to change Pactile phases, next-action hints, whether to create tasks, whether to use sub-agents, or when to check/wrap up, edit `.pactile/workflow.md` first.
-
-## Read These Files First
-
-1. `.pactile/workflow.md`
-2. Entry files for the current platform, such as skills/commands/prompts/workflows
-3. The selected task's `task.json` and `prd.md`
-
-## Common Needs And Edit Points
-
-| Need | Edit point |
-| --- | --- |
-| Change phase names or phase order | `Phase Index` and the corresponding Phase sections. |
-| Change whether to create a task when there is no task | `[workflow-state:no_task]` state block. |
-| Change the next step during planning | Phase 1 and `[workflow-state:planning]`. |
-| Change whether an agent is required during in_progress | Phase 2 and `[workflow-state:in_progress]`. |
-| Change wrap-up after completion | Phase 3 and `[workflow-state:completed]`. |
-| Change which skill a user intent triggers | `Skill Routing` table. |
-
-## Modification Steps
-
-1. Find the relevant section in `.pactile/workflow.md`.
-2. When changing rules, keep explicit trigger conditions and next actions.
-3. If adding or renaming a skill/agent, synchronize the corresponding files in platform directories.
-4. Workflow-state changes only need an edit to the `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The hook is parser-only — it reads whatever you put in the block. Keep the opening and closing tags' STATUS strings identical (`[workflow-state:foo]…[/workflow-state:foo]`); mismatched STATUS pairs are silently dropped.
-5. Make the AI reread `.pactile/workflow.md`; do not keep using rules from the old conversation.
-
-## Example: Relax Task Creation Requirements
-
-To change when task creation can be skipped, usually edit `[workflow-state:no_task]`:
-
-```md
-[workflow-state:no_task]
-Task is not required when the answer is a one-reply explanation, no files are changed, and no research is needed.
-[/workflow-state:no_task]
-```
-
-If the formal Phase 1 flow also needs to change, synchronize the Phase 1 section.
-
-## Example: One Platform Does Not Use Sub-Agents
-
-If the user wants only one platform to avoid sub-agents, first confirm whether that platform has a separate group in the workflow. Then change Phase 2 routing for that platform group instead of deleting all `pactile-implement` / `pactile-check` instructions across platforms.
-
-## `pactile-continue` Route Table
-
-`pactile-continue` (the continue skill; legacy projects may still invoke it as the `/pactile:continue` slash command) resumes a task by deciding which phase step to load next. The decision combines `task.json.status` with the presence of artifacts inside the task directory. The mapping is fixed in the skill itself; forks that add custom statuses must extend both the workflow.md tag block and this table.
-
-| `status` | Artifact state | Resume at |
-| --- | --- | --- |
-| `planning` | `prd.md` missing | Phase 1.1 (load `pactile-brainstorm`) |
-| `planning` | lightweight task with `prd.md` complete | run `task.py start-execution <task> --check`, ask for explicit execution approval, then run `--approved` |
-| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
-| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | run `task.py start-execution <task> --check`, ask for explicit execution approval, then run `--approved` |
-| `in_progress` | no implementation in conversation history | Phase 2.1 (`pactile-implement`) |
-| `in_progress` | implementation done, no `pactile-check` run | Phase 2.2 (`pactile-check`) |
-| `in_progress` | check passed | Phase 3.1 (verify quality + spec update) |
-| `completed` | task is still in active tree | Phase 3.5 (run `pactile-finish-work` to archive) |
-
-When you add a custom status (e.g. `in-review`), add a `[workflow-state:in-review]` block in `.pactile/workflow.md` for the per-turn breadcrumb AND extend this route table — usually by editing the `pactile-continue` skill (`.cursor/skills/pactile-continue/` or the equivalent command file) to add a row that decides where to resume from. Without the route entry, the resume flow will fall through to a default branch and the user will not land on the step you intended.
-
-## Notes
-
-`.pactile/workflow.md` is the local project workflow, not an immutable template. The user can adapt it to team habits. After editing it, platform entry files may still contain old descriptions, so inspect them too.
+# Change Local Workflow
+
+When the user wants to change Pactile phases, next-action hints, whether to create tasks, whether to use sub-agents, or when to check/wrap up, edit `.pactile/workflow.md` first.
+
+## Read These Files First
+
+1. `.pactile/workflow.md`
+2. Entry files for the current platform, such as skills/commands/prompts/workflows
+3. The selected task's `task.json` and `prd.md`
+
+## Common Needs And Edit Points
+
+| Need | Edit point |
+| --- | --- |
+| Change phase names or phase order | `Phase Index` and the corresponding Phase sections. |
+| Change whether to create a task when there is no task | `[workflow-state:no_task]` state block. |
+| Change the next step during planning | Phase 1 and `[workflow-state:planning]`. |
+| Change whether an agent is required during in_progress | Phase 2 and `[workflow-state:in_progress]`. |
+| Change wrap-up after completion | Phase 3 and `[workflow-state:completed]`. |
+| Change which skill a user intent triggers | `Skill Routing` table. |
+
+## Modification Steps
+
+1. Find the relevant section in `.pactile/workflow.md`.
+2. When changing rules, keep explicit trigger conditions and next actions.
+3. If adding or renaming a skill/agent, synchronize the corresponding files in platform directories.
+4. Workflow-state changes only need an edit to the `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The hook is parser-only — it reads whatever you put in the block. Keep the opening and closing tags' STATUS strings identical (`[workflow-state:foo]…[/workflow-state:foo]`); mismatched STATUS pairs are silently dropped.
+5. Make the AI reread `.pactile/workflow.md`; do not keep using rules from the old conversation.
+
+## Example: Relax Task Creation Requirements
+
+To change when task creation can be skipped, usually edit `[workflow-state:no_task]`:
+
+```md
+[workflow-state:no_task]
+Task is not required when the answer is a one-reply explanation, no files are changed, and no research is needed.
+[/workflow-state:no_task]
+```
+
+If the formal Phase 1 flow also needs to change, synchronize the Phase 1 section.
+
+## Example: One Platform Does Not Use Sub-Agents
+
+If the user wants only one platform to avoid sub-agents, first confirm whether that platform has a separate group in the workflow. Then change Phase 2 routing for that platform group instead of deleting all `pactile-implement` / `pactile-check` instructions across platforms.
+
+## `pactile-continue` Route Table
+
+`pactile-continue` (the continue skill; legacy projects may still invoke it as the `/pactile:continue` slash command) resumes a task by deciding which phase step to load next. The decision combines `task.json.status` with the presence of artifacts inside the task directory. The mapping is fixed in the skill itself; forks that add custom statuses must extend both the workflow.md tag block and this table.
+
+| `status` | Artifact state | Resume at |
+| --- | --- | --- |
+| `planning` | `prd.md` missing | Phase 1.1 (load `pactile-brainstorm`) |
+| `planning` | lightweight task with `prd.md` complete | run `pactile task start-execution <task> --check`, ask for explicit execution approval, then run `--approved` |
+| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
+| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | run `pactile task start-execution <task> --check`, ask for explicit execution approval, then run `--approved` |
+| `in_progress` | no implementation in conversation history | Phase 2.1 (`pactile-implement`) |
+| `in_progress` | implementation done, no `pactile-check` run | Phase 2.2 (`pactile-check`) |
+| `in_progress` | check passed | Phase 3.1 (verify quality + spec update) |
+| `completed` | task is still in active tree | Phase 3.5 (run `pactile-finish-work` to archive) |
+
+When you add a custom status (e.g. `in-review`), add a `[workflow-state:in-review]` block in `.pactile/workflow.md` for the per-turn breadcrumb AND extend the project-local `pactile-continue` entry under `.agents/skills/` if one exists. Without a route entry, the resume flow may fall through to a default branch.
+
+## Notes
+
+`.pactile/workflow.md` is the local project workflow, not an immutable template. The user can adapt it to team habits. After editing it, platform entry files may still contain old descriptions, so inspect them too.

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

@@ -1,55 +1,12 @@
-# Local Customization Overview
-
-This directory is for local AI working in a user project where Pactile was installed through npm and `pactile init` has already been run. The AI should modify generated `.pactile/` and platform directories inside the project, not Pactile CLI upstream source code.
-
-## First Determine What The User Actually Wants To Change
-
-| User wording | Read first |
-| --- | --- |
-| "Change the Pactile flow / phases / next prompt" | `change-workflow.md` |
-| "Change task creation, status, archive, or hooks" | `change-task-lifecycle.md` |
-| "AI did not read context / change injected content" | `change-context-loading.md` |
-| "A platform hook is not behaving as expected" | `change-hooks.md` |
-| "Change implement/check/research agent behavior" | `change-agents.md` |
-| "Add a skill/command/workflow/prompt" | `change-skills-or-commands.md` |
-| "Adjust the project spec structure" | `change-spec-structure.md` |
-| "Add team conventions and local notes" | `add-project-local-conventions.md` |
-
-## General Operation Order
-
-1. **Confirm platform and directories**: inspect which directories exist; on a fresh `pactile init --cursor` only `.cursor/` and `.pactile/` are created.
-2. **Confirm the selected task**: run `python3 ./.pactile/scripts/task.py selected --source`.
-3. **Read the local source of truth**: prefer `.pactile/workflow.md`, `.pactile/config.yaml`, and relevant platform files.
-4. **Modify narrowly**: edit only files related to the user's request.
-5. **Synchronize semantics**: if a shared flow changes, check whether platform entry points also need changes; if a platform entry changes, check whether `.pactile/workflow.md` still agrees.
-
-## Local File Priority
-
-| Layer | Files |
-| --- | --- |
-| Workflow | `.pactile/workflow.md` |
-| Project configuration | `.pactile/config.yaml` |
-| Task material | `.pactile/tasks/<task>/` |
-| Project specs | `.pactile/spec/` |
-| Runtime scripts | `.pactile/scripts/` |
-| Platform integration | `.cursor/` plus legacy adapter directories preserved by `pactile update` |
-| Shared skill | `.agents/skills/` |
-
-## Things Not To Do By Default
-
-- Do not edit the global npm install directory.
-- Do not edit `node_modules/@blxzer/pactile`.
-- Do not assume the user has the Pactile GitHub repository.
-- Do not overwrite local files already modified by the user with default templates.
-- Do not put team project rules into public `pactile-meta`; project rules belong in `.pactile/spec/` or a local skill.
-
-## When To Inspect Upstream Source
-
-Switch to an upstream source-code perspective only when the user explicitly expresses one of these goals:
-
-- "I want to open a PR to Pactile"
-- "I want to change npm package publish contents"
-- "I want to fork Pactile"
-- "I want to modify the generation logic for `pactile init/update`"
-
-Otherwise, default to modifying local Pactile files inside the user project.
+# Local customization
+
+Start by reading the project's `.pactile/workflow.md`, `.pactile/spec/`, managed `AGENTS.md` block, and `.agents/skills/`. Determine whether the target is framework-owned or user-owned from the ownership ledger.
+
+| Need | Change |
+| --- | --- |
+| Project coding convention | `.pactile/spec/` |
+| Local Skill | User-owned `.agents/skills/<name>/SKILL.md` |
+| Task decision or evidence | The task's PRD, implementation, or verification artifact |
+| Pactile product behavior | Product repository and tests |
+
+Do not edit a legacy host directory to add new Pactile behavior.

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

@@ -1,68 +1,68 @@
-# Local Context Injection System
-
-Pactile context injection aims to make AI read the right files at the right time instead of relying on model memory. In a user project, injection is implemented by `.pactile/` scripts together with platform hooks, agents, and skills.
-
-## Injected Context Types
-
-| Type | Source | Purpose |
-| --- | --- | --- |
-| session context | `.pactile/scripts/get_context.py` | Current developer, git status, selected task, Task Dashboard, active tasks, journal, packages. |
-| workflow context | `.pactile/workflow.md` | Current Pactile flow and next action. |
-| spec context | `.pactile/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
-| task context | `.pactile/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Selected task requirements, design, execution plan, and research. |
-| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
-
-## session-start
-
-Platforms with session-start support inject a Pactile overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
-
-- workflow summary.
-- selected task status.
-- active tasks.
-- spec index paths.
-- developer identity and git status.
-
-If the user feels the AI does not know the selected task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
-
-## workflow-state
-
-workflow-state is a lightweight hint injected around each user turn. Based on selected task status, it selects a block from `.pactile/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
-
-If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.pactile/workflow.md` first.
-
-## sub-agent context
-
-Implement and check agents need task context. Pactile has two loading modes:
-
-1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
-2. **agent pull**: the agent definition instructs the agent to read the selected task, jsonl context, and task artifacts after startup.
-
-In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
-
-## JSONL Reading Rules
-
-`implement.jsonl` and `check.jsonl` contain one JSON object per line:
-
-```jsonl
-{"file": ".pactile/spec/backend/index.md", "reason": "Backend rules"}
-```
-
-Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
-
-## Selected Task And Context Key
-
-Selected task state lives in `.pactile/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `PACTILE_CONTEXT_ID`.
-
-If shell commands cannot see the same context key, `task.py selected --source` may report no selected task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
-
-## Local Customization Points
-
-| Need | Edit location |
-| --- | --- |
-| Change session-start injected content | The platform's `session-start` hook or plugin file. |
-| Change per-turn workflow-state rules | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The platform workflow-state hook parses these blocks verbatim and embeds no fallback text. |
-| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
-| Change JSONL validation/display | `.pactile/scripts/common/task_context.py`. |
-| Change selected task resolution | `.pactile/scripts/common/active_task.py`. |
-
-When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.
+# Local Context Injection System
+
+Pactile context injection aims to make AI read the right files at the right time instead of relying on model memory. The Node CLI compiles context from `.pactile/` artifacts for the host and worker bridge.
+
+## Injected Context Types
+
+| Type | Source | Purpose |
+| --- | --- | --- |
+| session context | `pactile context` | Current developer, git status, selected task, Task Dashboard, active tasks, journal, packages. |
+| workflow context | `.pactile/workflow.md` | Current Pactile flow and next action. |
+| spec context | `.pactile/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
+| task context | `.pactile/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Selected task requirements, design, execution plan, and research. |
+| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
+
+## session-start
+
+Platforms with session-start support inject a Pactile overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
+
+- workflow summary.
+- selected task status.
+- active tasks.
+- spec index paths.
+- developer identity and git status.
+
+If the user feels the AI does not know the selected task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
+
+## workflow-state
+
+workflow-state is a lightweight hint injected around each user turn. Based on selected task status, it selects a block from `.pactile/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
+
+If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.pactile/workflow.md` first.
+
+## sub-agent context
+
+Implement and check agents need task context. Pactile has two loading modes:
+
+1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
+2. **agent pull**: the agent definition instructs the agent to read the selected task, jsonl context, and task artifacts after startup.
+
+In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
+
+## JSONL Reading Rules
+
+`implement.jsonl` and `check.jsonl` contain one JSON object per line:
+
+```jsonl
+{"file": ".pactile/spec/backend/index.md", "reason": "Backend rules"}
+```
+
+Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
+
+## Selected Task And Context Key
+
+Selected task state lives in `.pactile/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `PACTILE_CONTEXT_ID`.
+
+If shell commands cannot see the same context key, `pactile task selected --source` may report no selected task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change session-start injected content | The platform's `session-start` hook or plugin file. |
+| Change per-turn workflow-state rules | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The platform workflow-state hook parses these blocks verbatim and embeds no fallback text. |
+| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
+| Change JSONL validation/display | Pactile CLI Node implementation. |
+| Change selected task resolution | Pactile CLI Node implementation and platform session bridge. |
+
+When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.

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

@@ -1,83 +1,7 @@
-# Local Files Generated After Init
-
-`pactile init` writes the Pactile runtime into the user project. Later, `pactile update` tries to update Pactile-managed template files, but it uses `.pactile/.template-hashes.json` to determine which files have already been modified by the user.
-
-This page only describes files that are visible and editable inside the user project.
-
-## `.pactile/`
-
-```text
-.pactile/
-├── workflow.md
-├── config.yaml
-├── .developer
-├── .version
-├── .template-hashes.json
-├── .runtime/
-├── scripts/
-├── spec/
-├── tasks/
-└── workspace/
-```
-
-| Path | Usually editable? | Notes |
-| --- | --- | --- |
-| `.pactile/workflow.md` | Yes | Local workflow documentation and AI routing rules. |
-| `.pactile/config.yaml` | Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
-| `.pactile/spec/` | Yes | Project specs, intended to be updated regularly by users and AI. |
-| `.pactile/tasks/` | Yes | Task material and research artifacts, maintained by the task workflow. |
-| `.pactile/workspace/` | Yes | Session records, usually written by `add_session.py`. |
-| `.pactile/scripts/` | Carefully | Local runtime. It can be customized, but only after understanding the call chain. |
-| `.pactile/.runtime/` | No | Runtime state, usually written automatically by hooks/scripts. |
-| `.pactile/.developer` | Carefully | Current developer identity. |
-| `.pactile/.version` | No | Pactile version record used by update/migration logic. |
-| `.pactile/.template-hashes.json` | No | Template hash record. Do not hand-write business rules here. |
-
-## Platform Directories
-
-On a fresh `pactile init --cursor`, the only platform directory created is `.cursor/`. Pactile previously generated per-platform directories for many AI tools (`.claude/`, `.codex/`, `.opencode/`, etc.); those legacy directories are preserved by `pactile update` but new Pactile behavior ships to `.cursor/` only.
-
-Common categories inside `.cursor/`:
-
-| Category | Path | Purpose |
-| --- | --- | --- |
-| hooks | `.cursor/hooks/` | Hook scripts invoked from `.cursor/hooks.json`. Inject session context, workflow-state, and sub-agent context. |
-| settings/registration | `.cursor/hooks.json` | Registers which scripts run on which Cursor events. |
-| rules | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Per-turn policy prepended before every prompt. |
-| agents | `.cursor/agents/` | Define agents such as `pactile-research`, `pactile-implement`, and `pactile-check`. |
-| skills | `.cursor/skills/` | Skills that auto-trigger or can be read by AI. |
-| commands | `.cursor/commands/` | Legacy compatibility-only user-invoked entry points. |
-
-When modifying a platform directory, also confirm whether `.pactile/workflow.md` still describes the same flow.
-
-## Meaning Of Template Hashes
-
-`.pactile/.template-hashes.json` records the content hash from the last time Pactile wrote a template file. `pactile update` uses it to distinguish three cases:
-
-| Case | Update behavior |
-| --- | --- |
-| File was not modified by the user | It can be updated automatically. |
-| File was modified by the user | Prompt the user to overwrite, keep, or generate `.new`. |
-| File is no longer a current template | It may be deleted, renamed, or preserved according to migration rules. |
-
-When an AI customizes local Pactile files, it does not need to maintain hashes manually. It is normal for Pactile update to recognize the result as "modified by the user."
-
-## Local Customization Boundaries
-
-Editable by default:
-
-- `.pactile/workflow.md`
-- `.pactile/config.yaml`
-- `.pactile/spec/**`
-- `.pactile/scripts/**`
-- Platform hooks, settings, agents, skills, commands, prompts, and workflows
-
-Do not edit by default:
-
-- Global npm install directory
-- `node_modules/@blxzer/pactile`
-- Pactile GitHub repository source code
-- Concrete state files under `.pactile/.runtime/**`
-- Hash contents inside `.pactile/.template-hashes.json`
-
-Switch to the Pactile CLI source-code perspective only when the user explicitly wants to contribute upstream.
+# Generated files
+
+A new `pactile init --codex` prepares canonical framework files under `.pactile/`, a managed block in `AGENTS.md`, and shared Skills under `.agents/skills/`. Optional native Codex bindings depend on readiness.
+
+`.pactile/spec/`, tasks, workspace notes, and personal host settings are user-owned. `pactile update` reviews modified framework files before replacing them and does not treat a directory's existence as ownership.
+
+Old `.cursor/` assets may remain in upgraded projects. The active adapter does not refresh them; use `pactile detach cursor --dry-run` before legacy cleanup.