@blxzer/pactile 0.5.0 → 0.6.0-beta.4

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

@@ -1,77 +1,7 @@
-# Change Local Skills, Commands, Prompts, And Workflows
-
-When the user wants to change AI entry points, auto-trigger rules, or explicit command behavior, edit skills, commands, prompts, or workflows in local platform directories.
-
-## Read These Files First
-
-1. `.pactile/workflow.md`
-2. Target platform skill/command/prompt/workflow directory
-3. Related agent or hook files
-4. Whether project rules already exist in `.pactile/spec/`
-
-## Which Entry Type To Choose
-
-| Goal | Recommendation |
-| --- | --- |
-| AI should automatically know a capability | Add or modify a skill. |
-| User wants to trigger manually with a command | Add or modify a command/prompt/workflow. |
-| Team project conventions | Prefer `.pactile/spec/` or a project-local skill. |
-| Change Pactile flow semantics | Synchronize `.pactile/workflow.md`. |
-
-## Modify A Skill
-
-A skill is usually:
-
-```text
-<skill-name>/
-├── SKILL.md
-└── references/
-```
-
-`SKILL.md` should be short and responsible for triggering/routing. Put long content in `references/` so AI can read it on demand.
-
-For detailed skill authoring and review rules, use `pactile-skill-creator`. This `pactile-meta` page only identifies where local Pactile skill, command, prompt, and workflow changes belong.
-
-The frontmatter description should specify when to use the skill. Example:
-
-```yaml
-description: "Use when customizing this project's deployment workflow and release checklist."
-```
-
-Do not write vague descriptions such as "helpful project skill"; they can trigger incorrectly.
-
-## Modify A Command/Prompt/Workflow
-
-Explicit entry points should state:
-
-- How the user triggers it.
-- Which `.pactile/` files to read.
-- Which scripts to run.
-- How to report after completion.
-
-If a command only repeats workflow rules, prefer making it reference/read `.pactile/workflow.md` instead of maintaining a second copy of the flow.
-
-## Common Paths
-
-| Platform | Entry directories |
-| --- | --- |
-| Cursor | `.cursor/skills/` (preferred); `.cursor/commands/` is legacy compatibility-only |
-
-If a user project still contains legacy platform skill directories (`.claude/skills/`, `.codex/skills/`, etc.), inspect them but route new skill additions to `.cursor/skills/`.
-
-## Add A Project-Local Skill
-
-If the user wants to document team-private customizations, create a project-local skill, for example:
-
-```text
-.cursor/skills/project-pactile-local/
-└── SKILL.md
-```
-
-For shared skill layers across tools, consider `.agents/skills/` on platforms that read that path — but do not extend new Pactile behavior there; new Pactile behavior ships to `.cursor/skills/`.
-
-## Notes
-
-- Do not mix platform-specific syntax from removed adapters into the Cursor skill files.
-- Do not change only the dogfooded `.cursor/skills/` copy while forgetting to mirror the published template `packages/cli/src/templates/cursor/skills/` (and vice versa); see `cross-layer-thinking-guide.md.txt` → Cross-Package Template Consistency.
-- Do not hide long-term engineering conventions inside a command; write them to `.pactile/spec/`.
+# Change Skills or commands
+
+For project-specific guidance, add or edit a user-owned Skill under `.agents/skills/<name>/SKILL.md` or a relevant file in `.pactile/spec/`. Inspect names and ownership before writing.
+
+For lifecycle behavior, change the task contract or CLI command in the Pactile product source, then verify through the public CLI. A generated Skill is an entry point, not a second state store.
+
+Legacy host command and Skill directories are preserved for migration review only.

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

@@ -1,83 +1,83 @@
-# Change Local Spec Structure
-
-When the user wants to change the engineering conventions AI follows, add new spec layers, or adjust monorepo package mapping, edit `.pactile/spec/` and `.pactile/config.yaml`.
-
-## Read These Files First
-
-1. `.pactile/config.yaml`
-2. `.pactile/spec/`
-3. `.pactile/workflow.md` planning artifact guidance and Phase 3.3
-4. Selected task `implement.jsonl` / `check.jsonl`
-
-## Common Needs
-
-| Need | Edit location |
-| --- | --- |
-| Add backend/frontend/docs/test spec layer | `.pactile/spec/<layer>/` or `.pactile/spec/<package>/<layer>/` |
-| Add shared thinking guides | `.pactile/spec/guides/` |
-| Adjust monorepo packages | `packages` in `.pactile/config.yaml` |
-| Change default package | `default_package` in `.pactile/config.yaml` |
-| Control spec scanning scope | `spec_scope` in `.pactile/config.yaml` |
-| Make a task read a new spec | Task `implement.jsonl` / `check.jsonl` |
-
-## Add A Spec Layer
-
-Single-repository example:
-
-```text
-.pactile/spec/security/
-├── index.md
-└── auth.md
-```
-
-Monorepo example:
-
-```text
-.pactile/spec/webapp/security/
-├── index.md
-└── auth.md
-```
-
-`index.md` should include:
-
-- What code this layer applies to.
-- Pre-Development Checklist.
-- Quality Check.
-- Links to specific guideline files.
-
-## Update Context
-
-Adding a spec does not mean every task automatically reads it. The selected task must reference it in JSONL:
-
-```bash
-python3 ./.pactile/scripts/task.py add-context <task> implement ".pactile/spec/webapp/security/index.md" "Security conventions"
-python3 ./.pactile/scripts/task.py add-context <task> check ".pactile/spec/webapp/security/index.md" "Security review rules"
-```
-
-## Change Monorepo Packages
-
-Example `.pactile/config.yaml`:
-
-```yaml
-packages:
-  webapp:
-    path: apps/web
-  api:
-    path: apps/api
-default_package: webapp
-```
-
-After editing, run:
-
-```bash
-python3 ./.pactile/scripts/get_context.py --mode packages
-```
-
-Use this output to confirm AI can see the correct packages and spec layers.
-
-## Notes
-
-- Specs are user project conventions and can be changed according to project needs.
-- Do not put temporary task information into specs; put temporary information in the task.
-- Do not put long-term conventions only in agents or commands; preserve them in specs.
-- After changing spec structure, check whether existing task JSONL files still point to files that exist.
+# Change Local Spec Structure
+
+When the user wants to change the engineering conventions AI follows, add new spec layers, or adjust monorepo package mapping, edit `.pactile/spec/` and `.pactile/config.yaml`.
+
+## Read These Files First
+
+1. `.pactile/config.yaml`
+2. `.pactile/spec/`
+3. `.pactile/workflow.md` planning artifact guidance and Phase 3.3
+4. Selected task `implement.jsonl` / `check.jsonl`
+
+## Common Needs
+
+| Need | Edit location |
+| --- | --- |
+| Add backend/frontend/docs/test spec layer | `.pactile/spec/<layer>/` or `.pactile/spec/<package>/<layer>/` |
+| Add shared thinking guides | `.pactile/spec/guides/` |
+| Adjust monorepo packages | `packages` in `.pactile/config.yaml` |
+| Change default package | `default_package` in `.pactile/config.yaml` |
+| Control spec scanning scope | `spec_scope` in `.pactile/config.yaml` |
+| Make a task read a new spec | Task `implement.jsonl` / `check.jsonl` |
+
+## Add A Spec Layer
+
+Single-repository example:
+
+```text
+.pactile/spec/security/
+├── index.md
+└── auth.md
+```
+
+Monorepo example:
+
+```text
+.pactile/spec/webapp/security/
+├── index.md
+└── auth.md
+```
+
+`index.md` should include:
+
+- What code this layer applies to.
+- Pre-Development Checklist.
+- Quality Check.
+- Links to specific guideline files.
+
+## Update Context
+
+Adding a spec does not mean every task automatically reads it. The selected task must reference it in JSONL:
+
+```bash
+pactile task add-context <task> implement ".pactile/spec/webapp/security/index.md" "Security conventions"
+pactile task add-context <task> check ".pactile/spec/webapp/security/index.md" "Security review rules"
+```
+
+## Change Monorepo Packages
+
+Example `.pactile/config.yaml`:
+
+```yaml
+packages:
+  webapp:
+    path: apps/web
+  api:
+    path: apps/api
+default_package: webapp
+```
+
+After editing, run:
+
+```bash
+pactile context --mode packages
+```
+
+Use this output to confirm AI can see the correct packages and spec layers.
+
+## Notes
+
+- Specs are user project conventions and can be changed according to project needs.
+- Do not put temporary task information into specs; put temporary information in the task.
+- Do not put long-term conventions only in agents or commands; preserve them in specs.
+- After changing spec structure, check whether existing task JSONL files still point to files that exist.

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.