@blxzer/pactile 0.5.0 → 0.6.0-beta.2

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

@@ -1,84 +1,79 @@
-# Change Local Context Loading
-
-Context loading determines when AI reads workflow, task, spec, research, workspace, and git status. Read this page when the user says "AI does not know the selected task," "the agent did not read specs," or "there is too much/too little context."
-
-## Read These Files First
-
-1. `.pactile/workflow.md`
-2. `.pactile/scripts/get_context.py`
-3. `.pactile/scripts/common/session_context.py`
-4. `.pactile/scripts/common/task_context.py`
-5. `.pactile/scripts/common/active_task.py`
-6. Current platform hooks or agent files
-7. The selected task's `implement.jsonl` / `check.jsonl`
-
-## Context Sources
-
-| Source | Purpose |
-| --- | --- |
-| `.pactile/workflow.md` | Workflow and next-action hints. |
-| `.pactile/tasks/<task>/prd.md` | Selected task requirements. |
-| `.pactile/tasks/<task>/design.md` | Complex task technical design. |
-| `.pactile/tasks/<task>/implement.md` | Complex task execution plan. |
-| `.pactile/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
-| `.pactile/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
-| `.pactile/spec/` | Project specs. |
-| `.pactile/workspace/` | Session records. |
-| git status | Current working tree changes. |
-
-## Common Needs And Edit Points
-
-| Need | Edit point |
-| --- | --- |
-| Inject more/less information in new sessions | `session_context.py` or the platform `session-start` hook. |
-| Change hints on each user input | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The `inject-workflow-state` hook is parser-only and reads the block verbatim. |
-| Agent did not read specs | Task JSONL, agent prelude, `inject-subagent-context` hook. |
-| Selected task is lost | `active_task.py` and platform session identity propagation. |
-| Change JSONL validation rules | `task_context.py`. |
-
-## JSONL Rules
-
-`implement.jsonl` / `check.jsonl` are the key context loading interface:
-
-```jsonl
-{"file": ".pactile/spec/backend/index.md", "reason": "Backend conventions"}
-{"file": ".pactile/tasks/04-28-x/research/api.md", "reason": "API research"}
-```
-
-Include only spec/research files. Do not put code files that will be modified into these manifests; agents read code files themselves during implementation.
-
-## Change Session Context
-
-If the user wants every new session to see more project state, edit:
-
-- `.pactile/scripts/common/session_context.py`
-- the corresponding platform `session-start` hook
-
-Context cannot grow without bound. Prefer injecting indexes and paths so the AI can read detailed files on demand.
-
-## Change Sub-Agent Context
-
-First determine which mode the platform uses:
-
-- hook push: edit the `inject-subagent-context` hook.
-- agent pull: edit the read steps in the corresponding `pactile-implement` / `pactile-check` agent file.
-
-In both modes, make sure the agent ultimately reads:
-
-1. selected task
-2. the corresponding JSONL
-3. spec/research referenced by the JSONL
-4. `prd.md`
-5. `design.md` if present
-6. `implement.md` if present
-
-## Troubleshooting Order
-
-```bash
-python3 ./.pactile/scripts/task.py selected --source
-python3 ./.pactile/scripts/task.py list-context <task>
-python3 ./.pactile/scripts/task.py validate <task>
-python3 ./.pactile/scripts/get_context.py --mode packages
-```
-
-Confirm the task and JSONL are correct before editing hooks/agents.
+# Change Local Context Loading
+
+Context loading determines when AI reads workflow, task, spec, research, workspace, and git status. Read this page when the user says "AI does not know the selected task," "the agent did not read specs," or "there is too much/too little context."
+
+## Read These Files First
+
+1. `.pactile/workflow.md`
+2. `pactile context --mode session --json`
+3. `pactile task selected --source`
+4. Current platform hooks or agent files
+5. The selected task's `implement.jsonl` / `check.jsonl`
+
+## Context Sources
+
+| Source | Purpose |
+| --- | --- |
+| `.pactile/workflow.md` | Workflow and next-action hints. |
+| `.pactile/tasks/<task>/prd.md` | Selected task requirements. |
+| `.pactile/tasks/<task>/design.md` | Complex task technical design. |
+| `.pactile/tasks/<task>/implement.md` | Complex task execution plan. |
+| `.pactile/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
+| `.pactile/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
+| `.pactile/spec/` | Project specs. |
+| `.pactile/workspace/` | Session records. |
+| git status | Current working tree changes. |
+
+## Common Needs And Edit Points
+
+| Need | Edit point |
+| --- | --- |
+| Inject more/less information in new sessions | Project context manifests or the platform session entry. |
+| Change hints on each user input | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The `inject-workflow-state` hook is parser-only and reads the block verbatim. |
+| Agent did not read specs | Task JSONL, agent prelude, `inject-subagent-context` hook. |
+| Selected task is lost | `pactile task selected --source` and platform session identity propagation. |
+| Change JSONL validation rules | Pactile CLI Node implementation (product change). |
+
+## JSONL Rules
+
+`implement.jsonl` / `check.jsonl` are the key context loading interface:
+
+```jsonl
+{"file": ".pactile/spec/backend/index.md", "reason": "Backend conventions"}
+{"file": ".pactile/tasks/04-28-x/research/api.md", "reason": "API research"}
+```
+
+Include only spec/research files. Do not put code files that will be modified into these manifests; agents read code files themselves during implementation.
+
+## Change Session Context
+
+If the user wants every new session to see more project state, curate the project context manifests and the platform session entry. Changes to the compiler itself belong in the Pactile product source.
+
+Context cannot grow without bound. Prefer injecting indexes and paths so the AI can read detailed files on demand.
+
+## Change Sub-Agent Context
+
+For Pi Agent workers, determine which context loading mode the integration uses:
+
+- hook push: edit the `inject-subagent-context` hook.
+- agent pull: edit the read steps in the corresponding `pactile-implement` / `pactile-check` agent file.
+
+In both modes, make sure the agent ultimately reads:
+
+1. selected task
+2. the corresponding JSONL
+3. spec/research referenced by the JSONL
+4. `prd.md`
+5. `design.md` if present
+6. `implement.md` if present
+
+## Troubleshooting Order
+
+```bash
+pactile task selected --source
+pactile task list-context <task>
+pactile task validate <task>
+pactile context --mode packages
+```
+
+Confirm the task and JSONL are correct before editing hooks/agents.

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

@@ -1,57 +1,5 @@
-# Change Local Hooks
-
-Hooks are the automation layer that connects a platform to Pactile. When the user wants to change "when context is injected," "how shell commands inherit a session," or "which files are read before an agent starts," hooks are usually the edit point.
-
-## Read These Files First
-
-1. Target platform settings/config: `.cursor/hooks.json`
-2. Target platform hooks directory
-3. `.pactile/scripts/common/active_task.py`
-4. `.pactile/scripts/common/session_context.py`
-5. `.pactile/workflow.md`
-
-## Common Hook Types
-
-| Hook | Purpose |
-| --- | --- |
-| session-start | Injects a Pactile overview when a session starts, clears, or compacts. |
-| workflow-state | Injects a state hint on each user input. |
-| sub-agent context | Injects PRD/spec/research before an agent starts. |
-| shell session bridge | Lets `task.py` commands in shell see the same session identity. |
-
-## Modification Steps
-
-1. Find the hook registration in settings/config.
-2. Confirm the registered script path exists.
-3. Read the hook script and identify inputs, outputs, and called `.pactile/scripts/`.
-4. Modify hook behavior.
-5. If the hook depends on workflow content, synchronize `.pactile/workflow.md`.
-
-## Example: Change New-Session Injection Content
-
-First find the session-start hook:
-
-```text
-.cursor/hooks.json
-.cursor/hooks/session-start.py
-```
-
-If the hook ultimately calls `.pactile/scripts/get_context.py` or `session_context.py`, editing the local script is usually more robust than hard-coding content in the hook.
-
-## Example: Agent Did Not Read JSONL
-
-First confirm:
-
-```bash
-python3 ./.pactile/scripts/task.py selected --source
-python3 ./.pactile/scripts/task.py validate <task>
-```
-
-If the task and JSONL are correct, determine whether the platform uses hook push or agent pull. For hook push, edit `inject-subagent-context`; for agent pull, edit the agent file.
-
-## Notes
-
-- Settings handle registration, hook scripts handle behavior; inspect both together.
-- Cursor's hook event surface has changed between releases; confirm against the current Cursor build before wiring a new event.
-- Hooks should read project-local `.pactile/`; they should not depend on Pactile upstream source paths.
-- Hook failures should produce visible errors so AI does not silently lose context.
+# Change hooks
+
+Inspect actual project configuration and host readiness first. A hook file or declaration is not evidence that an event fired. Change only an owned, validated native binding and verify the resulting behavior in a test session.
+
+Keep personal host settings and credentials outside Pactile templates. Do not add Cursor hook registrations; the active install path no longer targets Cursor.

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.