@blxzer/pactile 0.5.0 → 0.6.0-beta.2

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.