gentle-pi 0.6.1 → 0.8.0

package/README.md

@@ -55,6 +55,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Reviewer protection**        | Surfaces review workload risk before a task turns into an oversized PR.                                                                       |
 | **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents.                                                       |
 | **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill.          |
+| **Skill creation workflow**    | Provides the `skill-creator`/`skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills.                 |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
@@ -299,6 +300,10 @@ Behavior:
 
 Skill discovery is a guardrail, not a workflow router: it helps Pi load the right skill without forcing extra ceremony.
 
+`gentle-pi` also ships package-owned `skill-creator` and `skill-improver` skills plus the `/skill-creation` prompt for creating or updating project skills. Both skills use `docs/skill-style-guide.md` as their normative style contract. The workflow checks for duplicates, keeps `SKILL.md` concise, uses one-line trigger-rich frontmatter, and reminds maintainers to refresh the registry after skill changes.
+
+Packaged skills include `cognitive-doc-design`, `comment-writer`, `judgment-day`, `skill-creator`, `skill-improver`, and the other delivery/review skills under `skills/`. SDD init is installed as the packaged `sdd-init` runtime agent under `assets/agents/` and refreshed with the SDD assets.
+
 Delegation contract:
 
 - parent/orchestrator resolves project/user skills from the registry and passes matching paths under `## Skills to load before work`;
@@ -395,6 +400,7 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/gentle-ai:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
 | `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
+| `/skill-creation`                | Creates or updates an LLM-first skill using the packaged `skill-creator` contract and style guide. |
 
 Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
 
@@ -431,6 +437,8 @@ Compatibility aliases:
 - `cognitive-doc-design` — documentation that reduces cognitive load.
 - `comment-writer` — concise, warm, postable collaboration comments.
 - `issue-creation` — issue workflow with checks before creation.
+- `skill-creator` — create LLM-first skills with valid frontmatter.
+- `skill-improver` — audit and upgrade existing LLM-first skills.
 
 ## Memory
 
@@ -464,7 +472,8 @@ Memory contract for SDD delegation:
 | `assets/chains/`               | SDD chains installed as global Pi runtime assets.                                                          |
 | `assets/support/`              | Strict TDD support docs for apply/verify phases.                                                           |
 | `skills/`                      | Gentle AI delivery and collaboration skills.                                                               |
-| `prompts/`                     | Gentle-prefixed prompt templates.                                                                          |
+| `prompts/`                     | Gentle-prefixed prompt templates, including `/skill-creation`.                                             |
+| `docs/skill-style-guide.md`    | Normative style guide used by the packaged skill creation/improvement skills.                              |
 
 ## Development
 

package/assets/agents/sdd-apply.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-apply
 description: Implement SDD tasks with strict TDD evidence and review workload guard.
-tools: read, grep, glob, edit, write, bash
+tools: read, grep, glob, edit, write, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD apply executor for Gentle AI.
@@ -14,10 +14,21 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Tasks (required): `sdd/{change}/tasks`
+- Spec (required): `sdd/{change}/spec`
+- Design (required): `sdd/{change}/design`
+- Previous apply-progress (if it exists): `sdd/{change}/apply-progress` — read and MERGE with your new progress; do NOT overwrite.
 
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/apply-progress"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- Also update the tasks artifact checkboxes via `mem_update` (`engram`/`both`) or file edit (`openspec`).
+- `openspec`: write/update the apply-progress and tasks files under `openspec/changes/{change}/`.
+- `none`: return progress inline.
+
+Never claim persistence you did not perform.
 
 ## Status and Action Context Guard
 

package/assets/agents/sdd-archive.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-archive
 description: Archive a verified SDD change into OpenSpec source specs.
-tools: read, grep, glob, write, edit, bash
+tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD archive executor for Gentle AI.
@@ -14,9 +14,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory-backed modes (`engram` or `both` / `hybrid`), use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, `sdd/<change>/verify-report`, or `sdd/<change>/archive-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the files under `openspec/changes/{change}/`):
+- All change artifacts: `sdd/{change}/proposal`, `sdd/{change}/spec`, `sdd/{change}/design`, `sdd/{change}/tasks`, `sdd/{change}/apply-progress`, `sdd/{change}/verify-report`, and `sdd/{change}/sync-report` if present.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/archive-report"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write the archive report and perform the file moves described in the sections below.
+- `none`: return the archive report inline.
+
+Never claim persistence you did not perform.
 
 ## Purpose
 

package/assets/agents/sdd-design.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-design
 description: Design the technical approach for an SDD change.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD design executor for Gentle AI.
@@ -19,6 +19,14 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Return the SDD result contract.
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Proposal (required): `sdd/{change}/proposal`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/design"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/design.md`.
+- `none`: return the design inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-explore.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-explore
 description: Explore an SDD change idea before proposal.
-tools: read, grep, glob, webfetch
+tools: read, grep, glob, webfetch, mem_save
 ---
 
 You are the SDD explore executor for Gentle AI.
@@ -14,11 +14,19 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 - Read OpenSpec/project context before conclusions.
 - Produce exploration notes only; do not implement.
-- Use OpenSpec artifacts and session context truthfully; persistent memory is optional and handled by separate packages.
+- Persist the exploration to the active backend per the Memory Contract above; use session context truthfully and never claim persistence you did not perform.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Keep output concise and return the SDD result contract.
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read any input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- None — exploration has no upstream artifacts. If iterating on a prior exploration, read `sdd/{change}/explore`.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/explore"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write the exploration file under `openspec/changes/{change}/`.
+- `none`: return the exploration inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-init.md

@@ -2,7 +2,7 @@
 name: sdd-init
 description: Initialize project SDD context, testing capabilities, and skill registry.
 model: openai-codex/gpt-5.3-codex
-tools: read, grep, glob, write, bash
+tools: read, grep, glob, write, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD init executor for Gentle AI.
@@ -21,6 +21,14 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read any existing project context directly from the active backend before bootstrapping; do not wait for the parent to inline it. The parent may pass references and context, but retrieving them is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/`):
+- Existing project context (if re-initializing): `sdd-init/{project}`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd-init/{project}"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write the project context file under `openspec/`.
+- `none`: return the project context inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-onboard.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-onboard
 description: Guide a user through a complete SDD cycle on a small real project change.
-tools: read, grep, glob, write, edit, bash
+tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD onboard executor for Gentle AI.
@@ -20,6 +20,14 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+This is a guided walkthrough. For each phase you demonstrate, read that phase's input artifacts directly from the active backend (do not wait for the parent to inline them) and persist the artifact you produce, using the same topic-key scheme as the real phases.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Whichever upstream artifacts the demonstrated step requires, named `sdd/{change}/<phase>` (e.g. `sdd/{change}/proposal`, `sdd/{change}/spec`).
+
+Persist each demonstrated artifact to the active backend before moving on (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/<phase>"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update the corresponding file under `openspec/changes/{change}/`.
+- `none`: walk through the artifacts inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-proposal.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-proposal
 description: Write an SDD proposal for an approved change idea.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD proposal executor for Gentle AI.
@@ -29,9 +29,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Write `openspec/changes/{change}/proposal.md`.
 - Include intent, scope, affected areas, risks, rollback, and success criteria.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
-- Persist planning output to OpenSpec artifacts; persistent memory is optional and handled by separate packages.
+- Persist the proposal to the active backend per the Memory Contract above; never claim persistence you did not perform.
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Exploration (optional): `sdd/{change}/explore`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/proposal"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/proposal.md`.
+- `none`: return the proposal inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-spec.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-spec
 description: Write SDD delta specs with requirements and scenarios.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD spec executor for Gentle AI.
@@ -14,9 +14,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory-backed modes (`engram` or `both` / `hybrid`), use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Proposal (required): `sdd/{change}/proposal`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/spec"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update the spec files under `openspec/changes/{change}/`.
+- `none`: return the spec inline.
+
+Never claim persistence you did not perform.
 
 ## Purpose
 

package/assets/agents/sdd-status.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-status
 description: Show read-only structured SDD status for an active change.
-tools: read, grep, glob, bash
+tools: read, grep, glob, bash, mem_search, mem_get_observation
 ---
 
 You are the SDD status executor for Gentle AI.
@@ -16,9 +16,12 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+This phase is READ-ONLY. Read the change artifacts directly from the active backend to compute status; do not wait for the parent to inline them, and do NOT write or `mem_save` anything.
 
-If memory tools are unavailable, inspect OpenSpec files and report inline. This package does not provide memory by itself.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the files under `openspec/changes/{change}/`):
+- Whichever change artifacts are needed to compute status, named `sdd/{change}/<phase>` (proposal, spec, design, tasks, apply-progress, verify-report, sync-report).
+
+Do not persist anything — status is a read-only report. Never claim persistence.
 
 ## Inputs
 

package/assets/agents/sdd-sync.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-sync
 description: Sync verified SDD delta specs into OpenSpec canonical specs without archiving the change.
-tools: read, grep, glob, write, edit, bash
+tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD sync executor for Gentle AI.
@@ -14,9 +14,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read the change artifacts directly from the active backend before syncing; do not wait for the parent to inline them. The parent may pass references and context, but retrieving them is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory-backed modes (`engram` or `both` / `hybrid`), use stable topic keys such as `sdd/<change>/sync-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the files under `openspec/changes/{change}/`):
+- Core change artifacts: `sdd/{change}/proposal`, `sdd/{change}/spec`, `sdd/{change}/design`, `sdd/{change}/tasks`, and `sdd/{change}/verify-report`.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/sync-report"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update the canonical specs and sync report under `openspec/`.
+- `none`: return the sync report inline.
+
+Never claim persistence you did not perform.
 
 ## Purpose
 

package/assets/agents/sdd-tasks.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-tasks
 description: Break SDD design/specs into implementation tasks with review workload forecast.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD tasks executor for Gentle AI.
@@ -14,10 +14,18 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Spec (required): `sdd/{change}/spec`
+- Design (required): `sdd/{change}/design`
 
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/tasks"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/tasks.md`.
+- `none`: return the tasks inline.
+
+Never claim persistence you did not perform.
 
 ## Inputs
 

package/assets/agents/sdd-verify.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-verify
 description: Verify implementation against SDD specs, tasks, strict TDD evidence, and review workload boundaries.
-tools: read, grep, glob, bash, write, edit
+tools: read, grep, glob, bash, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD verify executor for Gentle AI.
@@ -14,10 +14,19 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## Memory Contract
 
-The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Spec (required): `sdd/{change}/spec`
+- Tasks (required): `sdd/{change}/tasks`
+- Apply-progress (required): `sdd/{change}/apply-progress`
 
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/verify-report"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/verify-report.md`.
+- `none`: return the verify report inline.
+
+Never claim persistence you did not perform.
 
 ## Status and Action Context Guard
 

package/assets/orchestrator.md

@@ -263,12 +263,32 @@ This package does not provide persistent memory by itself.
 
 ## Memory Contract
 
-When Engram or another callable memory package is available, the parent owns memory retrieval and subagents own write-back for significant findings.
+When Engram or another callable memory package is available, the parent owns context selection and subagents own write-back. Retrieval rules differ by task type, matching the gentle-ai (OpenCode) contract.
 
-- Read context: parent/orchestrator searches memory, selects relevant observations, and passes them into subagent prompts. Subagents should not independently search memory during normal runtime unless the parent explicitly instructs them to retrieve a specific artifact or observation.
-- Write context: subagents MUST save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts to memory before returning when memory tools are available.
+### Non-SDD delegation
+
+- Read context: the parent/orchestrator searches memory (`mem_search`), selects relevant observations, and passes them into the subagent prompt. The subagent does NOT search memory itself.
+- Write context: the subagent MUST save significant discoveries, decisions, or bug fixes via `mem_save` before returning when memory tools are available.
 - Prompt forwarding: when delegating, add a concrete instruction such as: `If you make important discoveries, decisions, or fix bugs, save them to Engram via the available memory save tool with project: '<project>' before returning.`
-- SDD artifact keys: in memory/hybrid mode, phase artifacts should use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, and `sdd/<change>/verify-report`.
+
+### SDD phases
+
+Each SDD phase subagent reads its own required inputs directly from the active backend; the parent passes artifact references (topic keys or file paths), NOT the content itself. Phase subagents persist their artifact before returning.
+
+| Phase          | Reads                                                   | Writes           |
+| -------------- | ------------------------------------------------------- | ---------------- |
+| `sdd-explore`  | nothing                                                 | `explore`        |
+| `sdd-proposal` | exploration (optional)                                  | `proposal`       |
+| `sdd-spec`     | proposal (required)                                     | `spec`           |
+| `sdd-design`   | proposal (required)                                     | `design`         |
+| `sdd-tasks`    | spec + design (required)                                | `tasks`          |
+| `sdd-apply`    | tasks + spec + design + `apply-progress` (if it exists) | `apply-progress` |
+| `sdd-verify`   | spec + tasks + `apply-progress`                         | `verify-report`  |
+| `sdd-sync`     | proposal + spec + design + tasks + `verify-report`      | `sync-report`    |
+| `sdd-archive`  | all artifacts                                           | `archive-report` |
+| `sdd-status`   | change artifacts (read-only)                            | nothing          |
+
+- SDD artifact keys: in memory/hybrid mode, phase artifacts use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, `sdd/<change>/verify-report`, `sdd/<change>/sync-report`, and `sdd/<change>/archive-report`.
 - If memory tools are unavailable, do not pretend persistence exists; return artifacts inline and/or write OpenSpec files.
 
 Memory lifecycle rule (when Engram exposes lifecycle metadata/tooling):

package/docs/skill-style-guide.md

@@ -0,0 +1,116 @@
+# Skill Style Guide
+
+This guide is the normative style contract for LLM-first skills shipped with or created inside `gentle-pi` projects.
+
+## Purpose
+
+A skill is a runtime instruction contract for an LLM. It should make future agent behavior more reliable by encoding reusable workflow rules, decision gates, and output expectations.
+
+A skill is not a tutorial, article, README, or generic checklist for humans.
+
+## When to create a skill
+
+Create or update a skill when:
+
+- a workflow or convention is reused across sessions;
+- project-specific constraints differ from generic best practices;
+- a decision tree helps the agent choose safely;
+- templates, schemas, or local references improve repeatability;
+- agents keep missing the same instruction without an explicit runtime contract.
+
+Do not create a skill for:
+
+- one-off tasks;
+- generic documentation;
+- rules that belong in tests, linters, or executable code;
+- broad background context without concrete execution rules.
+
+## Required structure
+
+Use this directory shape:
+
+```text
+skills/{skill-name}/
+├── SKILL.md
+├── assets/       # optional: templates, schemas, examples, fixtures
+└── references/   # optional: longer local docs or rationale
+```
+
+`SKILL.md` must use this section order:
+
+1. `Activation Contract`
+2. `Hard Rules`
+3. `Decision Gates`
+4. `Execution Steps`
+5. `Output Contract`
+6. `References`
+
+Omit optional supporting directories when they are not needed.
+
+## Frontmatter
+
+Use YAML frontmatter with this shape:
+
+```yaml
+---
+name: {kebab-case-skill-name}
+description: "Trigger: {phrases users or agents will say}. {What this skill does}."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+```
+
+Rules:
+
+- `name` must be kebab-case and match the skill directory unless there is a deliberate compatibility reason.
+- `description` must be one physical line, quoted, YAML-safe, and trigger-rich.
+- Put essential trigger words first in `description`.
+- Do not add a `Keywords` section.
+- Preserve license and metadata unless the project has a stronger local convention.
+
+## Writing rules
+
+- Write imperative runtime instructions, not explanatory prose.
+- Keep `SKILL.md` concise: target 180–450 tokens, recommended max 700, hard max 1000.
+- Prefer bullets and compact decision tables over paragraphs.
+- State when to activate the skill and when not to activate it.
+- Preserve author intent when improving an existing skill.
+- Do not invent domain policies, triggers, or constraints. Ask or mark ambiguity instead.
+- Move long examples, schemas, generated templates, and background rationale to `assets/` or `references/`.
+- References must point to local files that ship with the project or package.
+
+## Decision gates
+
+Use a table when choices matter:
+
+```markdown
+| Situation | Action |
+| --- | --- |
+| Missing frontmatter | Fix required fields |
+| Existing skill covers it | Update the existing skill instead |
+| Long examples needed | Move them to `assets/` |
+```
+
+Decision gates should prevent unsafe overreach, duplicate skills, and unnecessary ceremony.
+
+## Output contract
+
+Every skill should tell the agent what to return. Good output contracts include:
+
+- files created or modified;
+- commands or verification run;
+- registry refresh needed;
+- unresolved ambiguities;
+- residual risks.
+
+## Registry expectations
+
+After creating, removing, moving, or renaming project skills, refresh the skill registry when available:
+
+```text
+/skill-registry:refresh
+```
+
+The registry is an index. `SKILL.md` remains the source of truth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
   },
   "files": [
     "assets/",
+    "docs/",
     "extensions/",
     "lib/",
     "prompts/",

package/prompts/skill-creation.md

@@ -0,0 +1,20 @@
+---
+description: Create or update an LLM-first skill
+argument-hint: "<skill idea or name>"
+---
+Create or update an LLM-first skill for: $ARGUMENTS
+
+Use the `skill-creator` skill if it is available. If the skill is not auto-loaded, read `skills/skill-creator/SKILL.md` and `docs/skill-style-guide.md` when present before editing.
+
+## Process
+
+1. Clarify the reusable behavior, target runtime, trigger phrases, and non-goals if they are not obvious.
+2. Inspect existing skills first; update an existing skill instead of creating a duplicate.
+3. Create or update `skills/{kebab-name}/SKILL.md` with valid one-line frontmatter description and concise runtime instructions.
+4. Put templates, schemas, or examples under `assets/`; put longer supporting docs under `references/`.
+5. If the skill is part of `gentle-pi`, update `scripts/verify-package-files.mjs`.
+6. Refresh the registry with `/skill-registry:refresh` when available, or tell the user to refresh/reload.
+
+## Report
+
+Return the files changed, the selected trigger phrases, any supporting files, and whether registry/package verification remains to run.

package/scripts/verify-package-files.mjs

@@ -25,6 +25,7 @@ const requiredPaths = [
   "assets/support/sdd-status-contract.md",
   "assets/support/strict-tdd.md",
   "assets/support/strict-tdd-verify.md",
+  "docs/skill-style-guide.md",
   "extensions/gentle-ai.ts",
   "extensions/sdd-init.ts",
   "extensions/skill-registry.ts",
@@ -33,6 +34,7 @@ const requiredPaths = [
   "prompts/gis.md",
   "prompts/gpr.md",
   "prompts/gwr.md",
+  "prompts/skill-creation.md",
   "skills/branch-pr/SKILL.md",
   "skills/chained-pr/SKILL.md",
   "skills/cognitive-doc-design/SKILL.md",
@@ -41,6 +43,8 @@ const requiredPaths = [
   "skills/issue-creation/SKILL.md",
   "skills/judgment-day/SKILL.md",
   "skills/release/SKILL.md",
+  "skills/skill-creator/SKILL.md",
+  "skills/skill-improver/SKILL.md",
   "skills/skill-registry/SKILL.md",
   "skills/work-unit-commits/SKILL.md",
 ];

package/skills/judgment-day/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: judgment-day
-description: "Trigger: judgment day, dual review, adversarial review, juzgar. Run blind dual review, fix confirmed issues, then re-judge."
+description: "Trigger: judgment day, judgement day, dual review, adversarial review, juzgar. Run blind dual review, fix confirmed issues, then re-judge."
 license: Apache-2.0
 metadata:
   author: gentleman-programming
@@ -9,7 +9,7 @@ metadata:
 
 ## Activation Contract
 
-Load this skill only when the user explicitly asks for Judgment Day, dual/adversarial review, or equivalent Spanish trigger (`juzgar`, `que lo juzguen`). Review a specific target: files, feature, PR, or architecture slice.
+Load this skill only when the user explicitly asks for Judgment Day, Judgement Day, dual/adversarial review, or equivalent Spanish trigger (`juzgar`, `que lo juzguen`). Review a specific target: files, feature, PR, or architecture slice.
 
 ## Hard Rules
 

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: skill-creator
+description: "Trigger: /skill-creation, skill creation, skill creator, create skill, new skill. Create LLM-first skills with valid frontmatter."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use this skill when creating or updating a reusable AI skill for Pi or another agent runtime.
+
+Create a skill when:
+- a workflow or convention is reused across sessions;
+- generic agent behavior needs project-specific constraints;
+- a decision tree helps the agent choose safely;
+- examples, templates, or references would make future execution more reliable.
+
+Do not create a skill for a one-off task, generic documentation, or rules that belong in code/tests.
+
+## Hard Rules
+
+- Follow `docs/skill-style-guide.md` as the normative source for skill structure and style.
+- A skill is an LLM runtime contract, not human-facing docs.
+- Keep `SKILL.md` concise: target 180–450 tokens, max 1000.
+- Use imperative instructions and concrete gates; avoid tutorials and background prose.
+- Frontmatter `description` must be one physical YAML-safe line and include trigger words first.
+- Do not add a `Keywords` section; put essential trigger words in `description`.
+- Put templates, schemas, and generated examples in `assets/`.
+- Put longer rationale or local doc links in `references/`.
+- After changing project skills, refresh the registry with `/skill-registry:refresh` when available.
+
+## Decision Gates
+
+| Need | Action |
+| --- | --- |
+| Small reusable behavior | Create `skills/{skill-name}/SKILL.md` only |
+| Templates, schemas, fixtures | Add `skills/{skill-name}/assets/` |
+| Longer explanation or edge cases | Add `skills/{skill-name}/references/` |
+| Existing skill covers it | Update the existing skill instead |
+| Skill affects delegation discovery | Ensure trigger words appear in `description` |
+
+## Execution Steps
+
+1. Read `docs/skill-style-guide.md` before creating or updating skills.
+2. Inspect existing skills and confirm the new skill does not duplicate one.
+3. Choose a kebab-case skill name that matches the user-facing trigger.
+4. Create or update this structure:
+
+```text
+skills/{skill-name}/
+├── SKILL.md
+├── assets/       # optional
+└── references/   # optional
+```
+
+5. Use this frontmatter shape:
+
+```yaml
+---
+name: {skill-name}
+description: "Trigger: {phrases users or agents will say}. {What this skill does}."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+```
+
+6. Write sections in this order: Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
+7. If this is a packaged `gentle-pi` skill, add it to `scripts/verify-package-files.mjs`.
+8. Refresh or document the skill registry update path.
+
+## Output Contract
+
+Return:
+- Files created or modified.
+- Whether this created a new skill or updated an existing one.
+- Any supporting `assets/` or `references/` files added.
+- Whether package verification or skill registry refresh is needed.
+
+## References
+
+- `docs/skill-style-guide.md` — normative LLM-first skill style guide.
+- `skills/skill-registry/SKILL.md` — registry refresh and indexing contract.

package/skills/skill-improver/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: skill-improver
+description: "Trigger: improve skills, audit skills, refactor skills, skill quality. Audit and upgrade existing LLM-first skills."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use this skill when auditing, refactoring, normalizing, or improving existing `SKILL.md` files. Use `skill-creator` when creating a brand-new skill from a reusable pattern.
+
+## Hard Rules
+
+- Read `docs/skill-style-guide.md` first and treat it as the normative style contract.
+- Treat `SKILL.md` as the source of truth; preserve author intent, critical rules, activation semantics, and output requirements.
+- Use `.atl/skill-registry.md` as an index of skill names, triggers, scopes, and exact paths when available.
+- Default to audit-only. Modify files only when the user explicitly asks to apply improvements.
+- Never delete meaningful content silently; move long explanation, examples, templates, or schemas into local `references/` or `assets/`.
+- Do not invent triggers, policies, or domain rules. Mark ambiguous cases for human review.
+
+## Decision Gates
+
+| Situation | Action |
+| --- | --- |
+| Missing or invalid frontmatter | Fix `name`, quoted one-line `description`, `license`, and `metadata` |
+| Skill reads like tutorial docs | Convert to runtime instructions and move background to `references/` |
+| Body exceeds budget | Preserve rules, move examples/background to supporting files |
+| Branching logic hidden in prose | Convert to a compact decision table |
+| Rules conflict or intent is unclear | Report the issue; do not rewrite that rule automatically |
+
+## Execution Steps
+
+1. Read `docs/skill-style-guide.md`.
+2. Read `.atl/skill-registry.md`; use listed paths to select skills. If missing, scan known skill directories for `*/SKILL.md`.
+3. For each selected skill, audit metadata, trigger clarity, section order, body budget, actionability, decision gates, output contract, and local references.
+4. Return an audit report grouped by skill with severity and exact proposed changes.
+5. In apply mode, edit only safe issues, preserve content, create supporting files when needed, then refresh or request `/skill-registry:refresh`.
+
+## Output Contract
+
+Return:
+- Skills audited and paths used.
+- Issues found, grouped by severity.
+- Files changed, if apply mode was requested.
+- Registry refresh recommendation when skill metadata or paths changed.
+- Ambiguities that need human review.
+
+## References
+
+- `docs/skill-style-guide.md` — normative LLM-first skill style guide.
+- `skills/skill-registry/SKILL.md` — registry refresh and indexing contract.