@blxzer/pactile 0.5.0 → 0.6.0-beta.4

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

@@ -1,69 +1,7 @@
-# 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.
+# Agent responsibilities
+
+The main Codex task owns planning, integration, verification, and final acceptance. Pactile does not install Codex subagent role files or dispatch Codex subagents.
+
+Independent Codex desktop tasks use App native tools with `pactile codex prepare|receipt|status` request and receipt records. The Node CLI cannot invoke those native tools itself. Record objective, task identity, and evidence; do not treat a message as acceptance.
+
+Use `.pactile/spec/` for project rules and `AGENTS.md` for concise managed entry instructions. Do not create agent files in a legacy host directory.

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

@@ -1,59 +1,7 @@
-# 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.
+# Hooks and settings
+
+A Pactile project may include a native Codex project binding when the host reports it is ready and the projection plan includes a validated fragment. Do not infer active delivery from a file's presence; verify the host's observed behavior.
+
+Canonical task state lives in `.pactile/`. Check the ownership ledger and current project files before changing any hook or setting. Keep credentials and personal host configuration outside product templates.
+
+The active install path does not create host hook registries or scripts. Existing host configuration remains outside the managed projection unless an explicit reviewed plan adopts it.

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

@@ -1,45 +1,5 @@
-# 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.
+# Codex project files
+
+Pactile stores canonical workflow, tasks, and runtime state in `.pactile/`. The active adapter projects managed instructions into `AGENTS.md` and shared Skills into `.agents/skills/`. Optional native Codex configuration is projected only when the host reports support and a reviewed plan supplies its binding.
+
+Inspect the project's ownership ledger before changing a generated file. Existing user content is not a template to overwrite. Files created by older host integrations remain user data unless the ledger proves Pactile ownership.

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

@@ -1,45 +1,9 @@
-# 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.
+# Active host map
+
+| Host | Init flag | Managed project files |
+| --- | --- | --- |
+| Codex desktop | `--codex` | `AGENTS.md`, `.agents/skills/`, and optional native project configuration |
+
+The current host integration is Codex. Pactile reports readiness before writing optional native bindings.
+
+Check actual files and `pactile capability-smoke --json` before assuming a native hook, MCP server, or plugin is active. `pactile codex` prepares native desktop task requests and records host-reported receipts; project files alone do not dispatch another task.

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

@@ -1,108 +1,7 @@
-# Skills, Commands, Prompts, And Workflows
-
-Skills and commands are textual entry points for user interaction with Pactile. They tell the AI how to enter the Pactile flow when the user expresses a certain intent.
-
-## Conceptual Differences
-
-| Type | Trigger mode | Best for |
-| --- | --- | --- |
-| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
-| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
-| prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
-| workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
-
-> Pactile previously shipped per-platform skill/command directories for many AI tools. The project has converged on **Cursor-only**. New skills and commands ship into `.cursor/`; legacy adapter directories in upgraded projects are preserved but not extended.
-
-Pactile has two skill families:
-
-- Workflow skills: `brainstorm`, `before-dev`, `check`, `update-spec`, and `break-loop`.
-- Multi-file bundled skills include `pactile-meta`, `pactile-spec-bootstrap`, `pactile-skill-creator`, `smart-search-cli`, and `pactile-micro-grill`.
-
-Bundled skills are installed as directories and may include nested `agents/`, `examples/`, `references/`, or other lazy-loadable files. Do not describe bundled skills as a closed `pactile-*` list: `smart-search-cli` intentionally keeps its existing non-`pactile-` name.
-
-`smart-search-cli` is CLI-backed source retrieval. The Pactile package exposes the `smart-search` executable through its runtime wrapper; the skill documents how agents should use that CLI and cite retrieved sources.
-
-`pactile-spec-bootstrap` bootstraps project-specific `.pactile/spec/` guidance from the real repository.
-
-`pactile-skill-creator` is the authoring and review guide for Pactile-compatible skills. Use it when creating or improving project-local skills under `.cursor/skills/`, the shared `.agents/skills/` directory (industry skill-sharing, kept but not extended by new Pactile behavior), or upstream bundled skills. Keep `pactile-meta` focused on architecture and routing.
-
-`pactile-micro-grill` is the Pactile clarification adapter. It asks one high-value question at a time and escalates to Lite, Full, or Parent/Child task modes only when durable artifacts or broader risk require it.
-
-## Common Paths (Cursor)
-
-| Platform | Common entries |
-| --- | --- |
-| Cursor | `.cursor/skills/` (preferred); `.cursor/commands/` is legacy compatibility-only |
-
-In a user project, use the files actually generated by init as authoritative. On current Cursor, Pactile prefers Agent Skills for manual entrypoints such as `pactile-continue` and `pactile-finish-work`; legacy `.cursor/commands/` files may exist in older projects but should be treated as an explicit compatibility surface rather than the default current-platform command surface.
-
-## Skill Structure
-
-A common skill is a directory:
-
-```text
-pactile-meta/
-├── SKILL.md
-└── references/
-pactile-spec-bootstrap/
-├── SKILL.md
-└── references/
-pactile-skill-creator/
-├── SKILL.md
-└── references/
-smart-search-cli/
-├── SKILL.md
-├── agents/
-├── examples/
-└── references/
-pactile-micro-grill/
-└── SKILL.md
-```
-
-`SKILL.md` should tell the AI:
-
-- When to use this skill.
-- Which reference to read first for the selected task.
-- What not to do.
-
-References hold longer explanations so the entry file does not contain everything.
-
-## Command/Prompt/Workflow Structure
-
-Commands, prompts, and workflows are usually single files. Their content should include:
-
-- When to use it.
-- Which `.pactile/` files to read.
-- Which scripts to run.
-- How to report after completion.
-
-They should not store task state; task state belongs in `.pactile/tasks/` and `.pactile/.runtime/`.
-
-Task selection uses `selected_task`, not legacy current/active task commands. The current command chain is:
-
-- `task.py dashboard` for routing without selecting a task.
-- `task.py select <task>` to select a task for the live session without changing `task.status`.
-- `task.py selected [--source]` to inspect the live-session selection.
-- `task.py start-execution <task> --check` and then `--approved` for the execution boundary.
-- `task.py exit` to clear the live-session selection without changing `task.status`.
-- `task.py archive <task>` for guarded completion.
-
-Do not reintroduce `task.py start`, `task.py current`, or `task.py finish` into platform commands or docs.
-
-## Local Change Scenarios
-
-| User need | Edit location |
-| --- | --- |
-| Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
-| Change user command behavior | The corresponding command/prompt/workflow file. |
-| Add a project-local skill | `.cursor/skills/` (or `.agents/skills/` only when explicitly sharing with another non-Pactile tool that reads that path). |
-| Change finish/continue entry points | On current Cursor, prefer `.cursor/skills/pactile-continue` and `.cursor/skills/pactile-finish-work` over legacy `.cursor/commands/`. |
-
-## Modification Principles
-
-1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `pactile-meta` and `pactile-skill-creator`.
-2. **Make trigger descriptions specific**. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
-3. **Keep behavior descriptions consistent with the shared `.pactile/` runtime**. Format may differ per file type, but semantics should match the shared workflow.
-4. **Put project-specific capabilities in local skills**. Do not put team-private flows into public `pactile-meta`.
-
-If the user only wants local AI to know one more project rule, usually create a project-local skill under `.cursor/skills/` or update `.pactile/spec/` instead of changing a Pactile built-in workflow skill.
+# Skills and commands
+
+Pactile projects expose managed Skills under `.agents/skills/`. Project-specific Skills can live there when the user owns them; inspect existing names and ownership before editing. Keep durable project conventions in `.pactile/spec/`.
+
+Use `pactile-skill-creator` when authoring a Skill. Keep `pactile-meta` focused on routing and architecture. The CLI owns task lifecycle commands; a Skill can explain when to run one, but its text does not prove that a command ran.
+
+Legacy host command directories are not active installation targets.

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

@@ -1,68 +1,68 @@
----
-name: pactile-micro-grill
-description: "Clarifies small underspecified Pactile requests with one high-value question at a time before direct execution. Use when a request is likely small, missing details would materially change the result, and creating a Pactile task would be premature."
----
-
-# Pactile Micro-Grill
-
-## Goal
-
-Clarify a small request just enough to execute it directly without creating Pactile task artifacts by default.
-
-## Hard Constraints
-
-- Always ask exactly one high-value question at a time.
-- Always inspect local files first when the missing answer is discoverable from the project.
-- Always include a recommended answer when enough evidence exists.
-- Always use Simplified Chinese for user-facing questions.
-- Never create Pactile task artifacts by default.
-- Never keep grilling after the request is clear enough to execute.
-- Never repeat already answered questions after escalation.
-
-## Thinking Principles
-
-These two principles shape *which* question is worth asking and *what* to recommend — apply them inside the one-question-per-message contract above.
-
-### First Principles
-
-Pick the question whose answer most changes the result by tracing the request back to its root user value, not to how similar requests are usually handled.
-
-- Separate the **root need** from **inherited shape** ("I want X like Y") — grill the root need first.
-- Prefer the question that, once answered, collapses the most other candidate questions.
-
-### Occam's Razor
-
-Your recommended answer defaults to the **minimal sufficient** option that still satisfies the likely acceptance bar. Complexity must be justified by evidence you can cite, not added speculatively. If two clarifications are equally valid, recommend the simpler one.
-
-## Workflow
-
-1. Confirm internally that the request is small, underspecified, and not already covered by a selected Pactile task.
-2. Inspect relevant local context first if it can answer the missing detail.
-3. Ask one question whose answer would most change the result.
-4. Include a recommended answer with the concrete tradeoff.
-5. After the user answers, summarize the clarified requirement in one or two Chinese sentences.
-6. Execute directly once the requirement is clear enough.
-
-## Frontier support (optional)
-
-Default is one question at a time (small-request clarification). When several questions can be asked together and their prerequisites are all decided (**≤3 questions**), list them in one round (numbered + recommended answers) and wait for a batch reply. Beyond that, keep one question at a time.
-
-Facts the environment can self-check do not consume question slots: self-check first (Hard Constraints: always inspect local files first); while a fact check is pending it only blocks the questions that depend on it — ask the rest of the frontier without blocking.
-
-## Escalation
-
-Escalate once when the clarified work no longer fits Micro-Grill:
-
-- Use Lite Task when there is one independently verifiable deliverable that needs persistence, review, or continuation.
-- Use Full Task when one deliverable has broad impact, platform-adapter changes, external research dependency, or durable design risk.
-- Use Parent/Child when there are multiple independently verifiable deliverables, staged execution, parallel execution, or Parent-controlled integration needs.
-
-When escalating, hand the clarified answers into `pactile-brainstorm` and update Pactile artifacts there.
-
-## When NOT to Use
-
-- Do not use for multi-deliverable work.
-- Do not use for cross-platform workflow changes.
-- Do not use for risky refactors, migrations, prompt deployments, or durable architecture decisions.
-- Do not use when the request is already clear enough to execute.
-- Do not use when there is already a selected Pactile task for the work.
+---
+name: pactile-micro-grill
+description: "Clarifies small underspecified Pactile requests with one high-value question at a time before direct execution. Use when a request is likely small, missing details would materially change the result, and creating a Pactile task would be premature."
+---
+
+# Pactile Micro-Grill
+
+## Goal
+
+Clarify a small request just enough to execute it directly without creating Pactile task artifacts by default.
+
+## Hard Constraints
+
+- Always ask exactly one high-value question at a time.
+- Always inspect local files first when the missing answer is discoverable from the project.
+- Always include a recommended answer when enough evidence exists.
+- Always use Simplified Chinese for user-facing questions.
+- Never create Pactile task artifacts by default.
+- Never keep grilling after the request is clear enough to execute.
+- Never repeat already answered questions after escalation.
+
+## Thinking Principles
+
+These two principles shape *which* question is worth asking and *what* to recommend — apply them inside the one-question-per-message contract above.
+
+### First Principles
+
+Pick the question whose answer most changes the result by tracing the request back to its root user value, not to how similar requests are usually handled.
+
+- Separate the **root need** from **inherited shape** ("I want X like Y") — grill the root need first.
+- Prefer the question that, once answered, collapses the most other candidate questions.
+
+### Occam's Razor
+
+Your recommended answer defaults to the **minimal sufficient** option that still satisfies the likely acceptance bar. Complexity must be justified by evidence you can cite, not added speculatively. If two clarifications are equally valid, recommend the simpler one.
+
+## Workflow
+
+1. Confirm internally that the request is small, underspecified, and not already covered by a selected Pactile task.
+2. Inspect relevant local context first if it can answer the missing detail.
+3. Ask one question whose answer would most change the result.
+4. Include a recommended answer with the concrete tradeoff.
+5. After the user answers, summarize the clarified requirement in one or two Chinese sentences.
+6. Execute directly once the requirement is clear enough.
+
+## Frontier support (optional)
+
+Default is one question at a time (small-request clarification). When several questions can be asked together and their prerequisites are all decided (**≤3 questions**), list them in one round (numbered + recommended answers) and wait for a batch reply. Beyond that, keep one question at a time.
+
+Facts the environment can self-check do not consume question slots: self-check first (Hard Constraints: always inspect local files first); while a fact check is pending it only blocks the questions that depend on it — ask the rest of the frontier without blocking.
+
+## Escalation
+
+Escalate once when the clarified work no longer fits Micro-Grill:
+
+- Use Lite Task when there is one independently verifiable deliverable that needs persistence, review, or continuation.
+- Use Full Task when one deliverable has broad impact, platform-adapter changes, external research dependency, or durable design risk.
+- Use Parent/Child when there are multiple independently verifiable deliverables, staged execution, parallel execution, or Parent-controlled integration needs.
+
+When escalating, hand the clarified answers into `pactile-brainstorm` and update Pactile artifacts there.
+
+## When NOT to Use
+
+- Do not use for multi-deliverable work.
+- Do not use for cross-platform workflow changes.
+- Do not use for risky refactors, migrations, prompt deployments, or durable architecture decisions.
+- Do not use when the request is already clear enough to execute.
+- Do not use when there is already a selected Pactile task for the work.

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

@@ -1,47 +1,47 @@
----
-name: pactile-skill-creator
-description: "Create or improve Pactile-compatible agent skills. Use when the user asks to author a project-local skill, shared .agents skill, platform-specific skill, or upstream Pactile bundled skill."
----
-
-# Pactile Skill Creator
-
-Create high-quality skills for Pactile-managed projects and Pactile bundled templates. This unified guide covers general authoring method plus Pactile packaging constraints.
-
-This skill is the authoring and review guide for skill files. It is not the local Pactile architecture map. Use `pactile-meta` first when the user needs to understand or customize `.pactile/`, hooks, settings, commands, prompts, workflows, agents, or platform directory layout.
-
-## Hard Constraints
-
-- Always inspect existing skill directories and platform conventions before creating or changing a skill.
-- Always keep `SKILL.md` under 500 lines, in English, and focused on trigger, constraints, workflow, references, and boundaries.
-- Always use lowercase letters, numbers, and hyphens in the frontmatter `name`.
-- Always write a trigger-rich frontmatter `description` that states what the skill does (WHAT) and when it should trigger (WHEN).
-- Always place safety, sequencing, and reliability rules in a `## Hard Constraints` section before `## Workflow`.
-- Always write Hard Constraints (and any other rule list) as imperative one-liners ("Always X. Never Y."). Never bury rules in prose paragraphs.
-- Always move long guidance, examples, prompts, and reference material into directly linked files.
-- Always make helper scripts deterministic, runnable from the skill directory, and explicit about inputs and outputs.
-- Never repeat the same rule in two sections — Hard Constraints is the single source of truth.
-- Never duplicate `pactile-meta` architecture guidance or project-private conventions inside a public Pactile skill.
-- Never edit Cursor's built-in `create-skill`; create or update Pactile-compatible skill files instead.
-
-## Workflow
-
-1. Classify the target skill location and read `references/pactile-skill-locations.md`.
-2. Gather requirements (six elements): purpose and scope, trigger scenarios, target location, domain constraints (tools / APIs / reliability), output style, and existing patterns. Infer from conversation context when available; ask the user when discrete choices are ambiguous. Capture tool budget and overlap with existing skills.
-3. Design, then draft: choose a specific skill name, write a trigger-rich description, decide script / no-script, and define success and stop criteria. Draft or revise `SKILL.md` using `references/authoring-rules.md` and `references/general-authoring.md`.
-4. Add `references/`, `examples/`, `prompts/`, or `scripts/` only when they reduce entry-file size or make execution more deterministic.
-5. Verify the result with `references/review-checklist.md`.
-6. Report changed files, validation performed, and any boundaries or follow-up work.
-
-## References
-
-- `references/pactile-skill-locations.md`: Choose project-local, shared, platform-specific, or upstream bundled skill locations.
-- `references/authoring-rules.md`: Frontmatter, trigger descriptions, hard-constraint form, progressive disclosure, writing-for-agents techniques, deterministic scripts, and anti-patterns.
-- `references/general-authoring.md`: General authoring method — principles, directory layout, patterns, utility scripts, and the minimal template.
-- `references/review-checklist.md`: Final quality checklist before handing off a skill change.
-
-## When NOT To Use
-
-- Do not use for general Pactile architecture discovery; use `pactile-meta`.
-- Do not use for project coding conventions that belong in `.pactile/spec/`.
-- Do not use for one-off commands or prompts unless the user wants a durable auto-triggered capability.
-- Do not use for non-Pactile global skill installation or platform configuration unless the user explicitly asks for that scope.
+---
+name: pactile-skill-creator
+description: "Create or improve Pactile-compatible agent skills. Use when the user asks to author a project-local skill, shared .agents skill, platform-specific skill, or upstream Pactile bundled skill."
+---
+
+# Pactile Skill Creator
+
+Create high-quality skills for Pactile-managed projects and Pactile bundled templates. This unified guide covers general authoring method plus Pactile packaging constraints.
+
+This skill is the authoring and review guide for skill files. It is not the local Pactile architecture map. Use `pactile-meta` first when the user needs to understand or customize `.pactile/`, hooks, settings, commands, prompts, workflows, agents, or platform directory layout.
+
+## Hard Constraints
+
+- Always inspect existing skill directories and platform conventions before creating or changing a skill.
+- Always keep `SKILL.md` under 500 lines, in English, and focused on trigger, constraints, workflow, references, and boundaries.
+- Always use lowercase letters, numbers, and hyphens in the frontmatter `name`.
+- Always write a trigger-rich frontmatter `description` that states what the skill does (WHAT) and when it should trigger (WHEN).
+- Always place safety, sequencing, and reliability rules in a `## Hard Constraints` section before `## Workflow`.
+- Always write Hard Constraints (and any other rule list) as imperative one-liners ("Always X. Never Y."). Never bury rules in prose paragraphs.
+- Always move long guidance, examples, prompts, and reference material into directly linked files.
+- Always make helper scripts deterministic, runnable from the skill directory, and explicit about inputs and outputs.
+- Never repeat the same rule in two sections — Hard Constraints is the single source of truth.
+- Never duplicate `pactile-meta` architecture guidance or project-private conventions inside a public Pactile skill.
+- Never edit a host's built-in Skill creator to implement a Pactile project Skill.
+
+## Workflow
+
+1. Classify the target skill location and read `references/pactile-skill-locations.md`.
+2. Gather requirements (six elements): purpose and scope, trigger scenarios, target location, domain constraints (tools / APIs / reliability), output style, and existing patterns. Infer from conversation context when available; ask the user when discrete choices are ambiguous. Capture tool budget and overlap with existing skills.
+3. Design, then draft: choose a specific skill name, write a trigger-rich description, decide script / no-script, and define success and stop criteria. Draft or revise `SKILL.md` using `references/authoring-rules.md` and `references/general-authoring.md`.
+4. Add `references/`, `examples/`, `prompts/`, or `scripts/` only when they reduce entry-file size or make execution more deterministic.
+5. Verify the result with `references/review-checklist.md`.
+6. Report changed files, validation performed, and any boundaries or follow-up work.
+
+## References
+
+- `references/pactile-skill-locations.md`: Choose project-local, shared, platform-specific, or upstream bundled skill locations.
+- `references/authoring-rules.md`: Frontmatter, trigger descriptions, hard-constraint form, progressive disclosure, writing-for-agents techniques, deterministic scripts, and anti-patterns.
+- `references/general-authoring.md`: General authoring method — principles, directory layout, patterns, utility scripts, and the minimal template.
+- `references/review-checklist.md`: Final quality checklist before handing off a skill change.
+
+## When NOT To Use
+
+- Do not use for general Pactile architecture discovery; use `pactile-meta`.
+- Do not use for project coding conventions that belong in `.pactile/spec/`.
+- Do not use for one-off commands or prompts unless the user wants a durable auto-triggered capability.
+- Do not use for non-Pactile global skill installation or platform configuration unless the user explicitly asks for that scope.