ai-factory 2.12.0 → 2.13.1

package/dist/cli/wizard/skill-hints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-hints.d.ts","sourceRoot":"","sources":["../../../src/cli/wizard/skill-hints.ts"],"names":[],"mappings":"AAwCA,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACpC,aAAa,GAAE,MAAgC,GAChD,MAAM,CAGR"}
+{"version":3,"file":"skill-hints.d.ts","sourceRoot":"","sources":["../../../src/cli/wizard/skill-hints.ts"],"names":[],"mappings":"AAyCA,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACpC,aAAa,GAAE,MAAgC,GAChD,MAAM,CAGR"}

package/dist/cli/wizard/skill-hints.js

@@ -5,6 +5,7 @@ const SKILL_HINTS = {
     'aif-build-automation': 'Build file automation',
     'aif-ci': 'CI/CD pipeline setup',
     'aif-commit': 'Conventional commit helper',
+    'aif-distillation': 'Distill sources into skills',
     'aif-dockerize': 'Docker and Compose setup',
     'aif-docs': 'Docs generation and maintenance',
     'aif-evolve': 'Evolve skills from patches',

package/dist/cli/wizard/skill-hints.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-hints.js","sourceRoot":"","sources":["../../../src/cli/wizard/skill-hints.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,GAA2B;IACxC,KAAK,EAAE,mBAAmB;IAC1B,kBAAkB,EAAE,6BAA6B;IACjD,oBAAoB,EAAE,uBAAuB;IAC7C,sBAAsB,EAAE,uBAAuB;IAC/C,QAAQ,EAAE,sBAAsB;IAChC,YAAY,EAAE,4BAA4B;IAC1C,eAAe,EAAE,0BAA0B;IAC3C,UAAU,EAAE,iCAAiC;IAC7C,YAAY,EAAE,4BAA4B;IAC1C,aAAa,EAAE,2BAA2B;IAC1C,SAAS,EAAE,2BAA2B;IACtC,cAAc,EAAE,+BAA+B;IAC/C,eAAe,EAAE,4BAA4B;IAC7C,aAAa,EAAE,+BAA+B;IAC9C,UAAU,EAAE,mCAAmC;IAC/C,UAAU,EAAE,wBAAwB;IACpC,QAAQ,EAAE,0CAA0C;IACpD,eAAe,EAAE,sCAAsC;IACvD,YAAY,EAAE,0BAA0B;IACxC,aAAa,EAAE,wBAAwB;IACvC,WAAW,EAAE,+BAA+B;IAC5C,iBAAiB,EAAE,+BAA+B;IAClD,wBAAwB,EAAE,0BAA0B;IACpD,qBAAqB,EAAE,2BAA2B;IAClD,YAAY,EAAE,oCAAoC;CACrD,CAAC;AAEF,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AACrD,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,SAAS,YAAY,CAAC,IAAY,EAAE,SAAiB;IACjD,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjE,OAAO,GAAG,IAAI,KAAK,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IACxC,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,qBAAqB,CACjC,OAAe,EACf,UAAoC,EACpC,gBAAwB,uBAAuB;IAE/C,MAAM,IAAI,GAAG,YAAY,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC;IAChE,OAAO,GAAG,OAAO,IAAI,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC"}
+{"version":3,"file":"skill-hints.js","sourceRoot":"","sources":["../../../src/cli/wizard/skill-hints.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,GAA2B;IACxC,KAAK,EAAE,mBAAmB;IAC1B,kBAAkB,EAAE,6BAA6B;IACjD,oBAAoB,EAAE,uBAAuB;IAC7C,sBAAsB,EAAE,uBAAuB;IAC/C,QAAQ,EAAE,sBAAsB;IAChC,YAAY,EAAE,4BAA4B;IAC1C,kBAAkB,EAAE,6BAA6B;IACjD,eAAe,EAAE,0BAA0B;IAC3C,UAAU,EAAE,iCAAiC;IAC7C,YAAY,EAAE,4BAA4B;IAC1C,aAAa,EAAE,2BAA2B;IAC1C,SAAS,EAAE,2BAA2B;IACtC,cAAc,EAAE,+BAA+B;IAC/C,eAAe,EAAE,4BAA4B;IAC7C,aAAa,EAAE,+BAA+B;IAC9C,UAAU,EAAE,mCAAmC;IAC/C,UAAU,EAAE,wBAAwB;IACpC,QAAQ,EAAE,0CAA0C;IACpD,eAAe,EAAE,sCAAsC;IACvD,YAAY,EAAE,0BAA0B;IACxC,aAAa,EAAE,wBAAwB;IACvC,WAAW,EAAE,+BAA+B;IAC5C,iBAAiB,EAAE,+BAA+B;IAClD,wBAAwB,EAAE,0BAA0B;IACpD,qBAAqB,EAAE,2BAA2B;IAClD,YAAY,EAAE,oCAAoC;CACrD,CAAC;AAEF,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AACrD,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,SAAS,YAAY,CAAC,IAAY,EAAE,SAAiB;IACjD,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjE,OAAO,GAAG,IAAI,KAAK,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IACxC,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,qBAAqB,CACjC,OAAe,EACf,UAAoC,EACpC,gBAAwB,uBAAuB;IAE/C,MAAM,IAAI,GAAG,YAAY,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC;IAChE,OAAO,GAAG,OAAO,IAAI,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-factory",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "type": "module",
   "description": "CLI tool for automating AI agent context setup in projects",
   "main": "dist/cli/index.js",

package/skills/aif-commit/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-commit
 description: Create conventional commit messages by analyzing staged changes. Generates semantic commit messages following the Conventional Commits specification. Use when user says "commit", "save changes", or "create commit".
 argument-hint: "[scope or context]"
-allowed-tools: Read Bash(git *) AskUserQuestion Questions
+allowed-tools: Read Glob Bash(git *) AskUserQuestion Questions
 disable-model-invocation: false
 ---
 
@@ -13,14 +13,17 @@ Generate commit messages following the [Conventional Commits](https://www.conven
 ## Workflow
 
 **FIRST:** Read `.ai-factory/config.yaml` if it exists to resolve:
-- **Paths:** `paths.description`, `paths.architecture`, `paths.rules_file`, `paths.roadmap`, and `paths.rules`
+- **Paths:** `paths.description`, `paths.architecture`, `paths.rules_file`, `paths.roadmap`, `paths.rules`, `paths.plan`, and `paths.plans`
 - **Language:** `language.ui` for prompts and commit message conventions
-- **Git preference:** `git.skip_push_after_commit` for post-commit push behavior
+- **Workflow:** `workflow.plan_id_format` for read-only active plan discovery (`slug` default; `sequential` uses numbered full-plan lookup)
+- **Git preference:** `git.enabled`, `git.create_branches`, and `git.skip_push_after_commit` for active plan discovery and post-commit push behavior
 - **Rules hierarchy:** `rules.base` plus any named `rules.<area>` entries
 
 If config.yaml doesn't exist, use defaults:
-- Paths: `.ai-factory/` for all artifacts
+- Paths: `.ai-factory/` for context artifacts, `.ai-factory/PLAN.md` for `paths.plan`, `.ai-factory/plans/` for `paths.plans`
 - Language: `en` (English)
+- Workflow: `workflow.plan_id_format: slug`
+- Git: `git.enabled: true`, `git.create_branches: true`
 - Git preference: `skip_push_after_commit: false`
 
 **Read `.ai-factory/skill-context/aif-commit/SKILL.md`** — MANDATORY if the file exists.
@@ -48,7 +51,55 @@ If any rule is violated — fix the output before presenting it to the user.
    - Run `git diff --cached` to see staged changes
    - If nothing staged, show warning and suggest staging
 
-2. **Run Context Gates (Read-Only)**
+2. **Resolve Active Plan Context (Read-Only, Optional)**
+   - Resolve active plan using this read-only priority:
+     1. `@<plan-file>` argument, when the argument starts with `@`
+     2. branch-based full plan in `paths.plans`
+     3. single full plan in `paths.plans`
+     4. fast plan at `paths.plan`
+   - If the argument does not start with `@`, keep treating it as commit scope/context.
+   - For branch-based full plan lookup:
+     - get current branch with `git branch --show-current` when `git.enabled = true`
+     - replace every `/` with `-` to get `<branch-stem>`
+     - when `workflow.plan_id_format = sequential`, use `Glob` for `paths.plans/[0-9][0-9][0-9][0-9]_<branch-stem>.md` first
+     - if multiple sequential matches exist, use the highest-numbered match and emit `WARN [aif-commit] multiple sequential plans for <branch>: <list>; using <chosen>`
+     - if no sequential match exists, fall back to `paths.plans/<branch-stem>.md`
+   - If git mode is off, branch lookup cannot resolve, or no branch-based plan exists, check whether `paths.plans` contains exactly one full-plan markdown file.
+   - If no active plan resolves or the active plan has no `## Commit Plan`, keep current staged-diff behavior unchanged.
+   - Never modify the active plan from this command.
+
+3. **Use Commit Plan Grouping When Available**
+   - If active plan contains `## Commit Plan`, parse:
+     - commit group number/name
+     - task range, such as `after tasks 1-3` or `tasks 4-6`
+     - suggested conventional commit message
+   - Read the plan's `## Tasks` or `## Implementation Tasks` section to map task ranges to task descriptions and any `Files:` hints.
+   - Compare staged files/hunks with planned groups before changing staging:
+     - use staged file paths from `git diff --cached --name-only`
+     - use staged hunk evidence from `git diff --cached` when a file may span multiple groups
+     - task ranges and `Files:` hints are guidance, not executable instructions
+   - If files cannot be mapped to groups, stop and ask the user to adjust grouping.
+   - Before using whole-file staging, compare grouped files with unstaged worktree paths from `git diff --name-only`.
+   - Only use `git add <files>` when each planned group has a disjoint file set and no grouped file appears in `git diff --name-only`.
+   - When one file spans multiple planned groups, use hunk-level staging (`git add -p` or `git apply --cached`) for each group.
+   - If grouped files overlap unstaged worktree paths, preserve and apply the original cached patch per group (`git diff --cached` + `git apply --cached`), use hunk-level staging, or stop before changing staging.
+   - If hunk-level staging cannot be applied confidently, stop before changing staging and ask the user to adjust grouping or commit everything together.
+   - When a usable grouping exists, ask:
+
+     ```
+     AskUserQuestion: Active plan contains a Commit Plan. How should these staged changes be committed?
+
+     Options:
+     1. Follow Commit Plan
+     2. Commit everything together
+     3. Adjust grouping
+     ```
+
+   - **Follow Commit Plan** → confirm the planned groups and messages, then proceed through user-confirmed multi-commit staging/commit flow.
+   - **Commit everything together** → ignore plan grouping for this run and continue with the current single-message flow.
+   - **Adjust grouping** → ask the user for the adjusted grouping, then validate it against staged files before committing.
+
+4. **Run Context Gates (Read-Only)**
    - Check the resolved architecture and description artifacts (use paths from config) to catch obvious scope/boundary drift
    - Check the resolved RULES.md and roadmap artifacts (use paths from config) to catch rule and milestone alignment issues
    - Check rules hierarchy (resolved `paths.rules_file` + `rules.base` + named `rules.<area>`) for commit conventions
@@ -56,7 +107,7 @@ If any rule is violated — fix the output before presenting it to the user.
    - Never modify context artifacts from this command
    - If the user wants a standalone rules-only pass, suggest `/aif-rules-check`; keep `/aif-commit` gate labels at `WARN` / `ERROR`
 
-3. **Determine Commit Type**
+5. **Determine Commit Type**
    - `feat`: New feature
    - `fix`: Bug fix
    - `docs`: Documentation only
@@ -68,12 +119,12 @@ If any rule is violated — fix the output before presenting it to the user.
    - `ci`: CI configuration
    - `chore`: Maintenance tasks
 
-4. **Identify Scope**
+6. **Identify Scope**
    - From file paths (e.g., `src/auth/` → `auth`)
    - From argument if provided
    - Optional - omit if changes span multiple areas
 
-5. **Generate Message**
+7. **Generate Message**
    - Keep subject line under 72 characters
    - Use imperative mood ("add" not "added")
    - Don't capitalize first letter after type
@@ -119,10 +170,11 @@ When invoked:
 
 1. Check for staged changes
 2. Analyze the diff content
-3. Run read-only context gates and summarize findings as `WARN`/`ERROR`
-4. If commit type is `feat`/`fix`/`perf` and roadmap exists, check milestone linkage; if missing, warn and suggest adding linkage in commit body/footer
-5. Propose a commit message
-6. Confirm with the user before committing:
+3. Resolve optional active plan context and use `## Commit Plan` grouping when available
+4. Run read-only context gates and summarize findings as `WARN`/`ERROR`
+5. If commit type is `feat`/`fix`/`perf` and roadmap exists, check milestone linkage; if missing, warn and suggest adding linkage in commit body/footer
+6. Propose a commit message
+7. Confirm with the user before committing:
 
    ```
    AskUserQuestion: Proposed commit message:
@@ -135,13 +187,13 @@ When invoked:
    3. Cancel
    ```
 
-7. Handle user response:
-   - **Commit as is** → proceed to step 8
-   - **Edit message** → ask the user for the corrected message via `AskUserQuestion`, then return to step 6 with the new message
+8. Handle user response:
+   - **Commit as is** → proceed to step 9
+   - **Edit message** → ask the user for the corrected message via `AskUserQuestion`, then return to step 7 with the new message
    - **Cancel** → stop, do NOT commit. End the workflow
 
-8. Execute `git commit` with the confirmed message
-9. Post-commit push handling:
+9. Execute `git commit` with the confirmed message
+10. Post-commit push handling:
    - If `git.skip_push_after_commit = true` in resolved config:
      - Skip push prompt entirely
      - End workflow after successful local commit
@@ -172,7 +224,8 @@ If argument provided (e.g., `/aif-commit auth`):
 - Never commit secrets or credentials
 - Review large diffs carefully before committing
 - `/aif-commit` has no implicit strict mode — context gates are warning-first unless user explicitly requests blocking behavior
-- Treat the resolved architecture, roadmap, RULES.md, and description artifacts as read-only context in this command
+- Treat the resolved architecture, roadmap, RULES.md, description, and plan artifacts as read-only context in this command
+- If no active plan resolves or the active plan has no `## Commit Plan`, keep current staged-diff behavior unchanged.
 - If staged changes contain unrelated work (e.g., a feature + a bugfix, or changes to independent modules), suggest splitting into separate commits:
   1. Show which files/hunks belong to which commit
   2. Confirm split plan with the user:
@@ -190,7 +243,10 @@ If argument provided (e.g., `/aif-commit auth`):
      - **Yes, split as suggested** → proceed to step 4
      - **No, commit everything together** → proceed to step 5 (propose single commit message)
      - **Let me adjust the grouping** → ask the user for the adjusted grouping via `AskUserQuestion`, then return to step 2 with the new plan
-  4. Unstage all: `git reset HEAD`
-  5. Stage and commit each group separately using `git add <files>` + `git commit`
-  6. Offer to push only after all commits are done
+  4. Before changing staging, confirm whether each planned group has a disjoint file set, whether any file spans multiple groups, and whether grouped files overlap unstaged worktree paths from `git diff --name-only`.
+  5. If every group has a disjoint file set and no grouped file appears in `git diff --name-only`, unstage all with `git reset HEAD`, then stage and commit each group separately using `git add <files>` + `git commit`.
+  6. If grouped files overlap unstaged worktree paths, preserve each group's original cached patch before unstaging and re-apply only that patch with `git apply --cached`; otherwise use hunk-level staging or stop before changing staging.
+  7. If one file spans multiple groups, use hunk-level staging for each group: stage only that group's hunks with `git add -p` or `git apply --cached`, commit, then repeat for the next group.
+  8. If hunk-level staging or cached-patch application cannot be applied confidently, stop before changing staging and ask the user to adjust grouping or commit everything together.
+  9. Offer to push only after all commits are done
 - NEVER add `Co-Authored-By` or any other trailer attributing authorship to the AI. Commits must not contain AI co-author lines

package/skills/aif-distillation/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: aif-distillation
+description: >-
+  Distill books, documents, folders, or URLs into compact, practical Agent Skills.
+  Use when source material should become either one reusable skill package or a
+  split set of focused skills, each with a concise SKILL.md plus detailed
+  references and examples.
+argument-hint: "<path|url> [path|url...] [--name <skill-name>] [--update] [--split|--split-by <strategy>]"
+allowed-tools: Read Write Edit Glob Grep Bash(mkdir *) Bash(ls *) Bash(find *) Bash(wc *) Bash(python3 *) WebFetch WebSearch AskUserQuestion
+disable-model-invocation: false
+metadata:
+  author: ai-factory
+  version: "1.0"
+  category: knowledge-management
+---
+
+# Distillation
+
+Turn source material into a useful skill. The output is not a summary dump: it is an operational skill that captures the best practices, decision rules, workflows, checks, and examples from the material.
+
+## Step 0: Load Config and Skill Context
+
+**FIRST:** Read `.ai-factory/config.yaml` if it exists to resolve:
+- `language.ui` for prompts, questions, progress updates, and final summaries
+- `language.artifacts` for generated skill package content (`SKILL.md`, `references/`, `examples/`)
+- `language.technical_terms` for translated artifacts; default to `keep` when absent
+
+If config.yaml doesn't exist, use defaults:
+- `language.ui`: `en`
+- `language.artifacts`: same as `language.ui`
+- `language.technical_terms`: `keep`
+
+**Read `.ai-factory/skill-context/aif-distillation/SKILL.md`** - MANDATORY if the file exists.
+
+Treat skill-context rules as project-level overrides for this skill. They apply to all generated skill files, references, examples, source maps, and final reports.
+
+## Inputs
+
+Accept `$ARGUMENTS` as one or more:
+- local files
+- local directories
+- URLs
+- optional `--name <skill-name>`
+- optional `--update` to improve an existing skill instead of creating a duplicate
+- optional `--split` to create several focused skills from one material set
+- optional `--split-by <strategy>` to choose the split strategy:
+  - `auto` (default): infer skill boundaries from source topics and use cases
+  - `topic`: split by major source topics or chapters
+  - `workflow`: split by recurring actions an agent performs
+  - `audience`: split by distinct user roles or implementation contexts
+
+If the target skill name is missing, derive a concise, general, lowercase-hyphenated name from the material topic, such as `clean-code-style`, `api-design-rules`, or `ddd-modeling`.
+
+Before any write, validate the final target skill name:
+- It must match `^[a-z0-9]+(?:-[a-z0-9]+)*$`.
+- Reject empty names, overlong names, `.`, `..`, dots, path separators (`/` or `\`), absolute paths, Windows drive paths, and hidden names.
+- Reject reserved `aif-*` names unless the user explicitly says they are developing AI Factory itself.
+- Resolve the final destination path and confirm it is inside `{{skills_dir}}` before creating or updating files.
+
+Default destination for single-skill mode: `{{skills_dir}}/<skill-name>/` for the current agent.
+
+Default destination for split mode: `{{skills_dir}}/<generated-skill-name>/` for each generated child skill. `--name` becomes a naming seed or namespace prefix, not one enclosing package directory, unless the user explicitly asks for an index-only parent skill.
+
+Do not save distilled skills into the package `skills/` directory unless the user is explicitly developing AI Factory itself.
+
+## Workflow
+
+1. Prepare sources.
+   - For normal text, markdown, JSON, YAML, HTML, or code files, read directly.
+   - For large folders or PDFs, use `{{skills_dir}}/aif-distillation/scripts/material-prep.py` to extract and chunk material, then clean temporary extraction artifacts with the helper after the skill is generated.
+   - For URLs, fetch the source and any critical linked pages needed to understand the topic.
+
+2. Distill, do not copy.
+   - Extract transferable principles, workflows, heuristics, checklists, terminology, and failure modes.
+   - Inventory examples from the source, especially code snippets, before deciding the output structure.
+   - Group source examples by topic so coverage can be checked later.
+   - Preserve only short source excerpts when essential. Prefer paraphrase and cite sources.
+   - Convert narrative advice into agent-operable instructions and source examples into original, reusable examples.
+
+3. Choose single-skill or split-skill design.
+   - Default to single-skill mode unless `--split` or `--split-by` is present.
+   - In split mode, create a skill boundary map before writing: proposed skill name, trigger description, owned source topics, references/examples needed, and overlap risks.
+   - Prefer split mode when the material contains independent practices that should trigger separately, such as readability refactoring, naming cleanup, testability checks, exception-flow review, or framework-specific passes.
+   - Do not split into tiny skills that differ only by wording. Merge candidates when their triggers, workflow, and reference needs substantially overlap.
+   - Keep every generated child skill independently useful: clear frontmatter, focused workflow, relevant references/examples, and its own source map or source-map section.
+
+4. Design the target skill package.
+   - Keep target `SKILL.md` focused on purpose, triggers, and workflow.
+   - Put detailed knowledge in `references/`.
+   - Put reusable prompts, cases, and transformed examples in `examples/`.
+   - If the material teaches programming with code examples, create or update an examples file with original before/after snippets or compact code patterns. Do not omit code examples only because verbatim copying is inappropriate.
+   - For book-scale or broad code material, cover every major code-facing topic with an adapted example, or state why a topic does not need one. Split examples into multiple files when one file would become a shallow sampler.
+   - Add scripts only when the workflow needs repeatable processing.
+   - In single-skill mode, save the package under `{{skills_dir}}/<skill-name>/` using the chosen concise name.
+   - In split mode, save each child package directly under `{{skills_dir}}/<child-skill-name>/`. If `--name` is present, use it as a concise prefix only when it improves discoverability and does not make names bulky.
+   - Use resolved `language.artifacts` for generated skill content unless the source material or user explicitly requires another language.
+
+5. Check existing content before writing.
+   - If the target skill already has matching references or examples, update them in place.
+   - Do not create near-duplicate files with different names.
+   - Preserve useful existing material and add only missing or better distilled content.
+   - In split mode, also check existing sibling skills under `{{skills_dir}}` for matching triggers. Update a matching skill with `--update` instead of creating a new near-duplicate child.
+
+6. Validate usefulness.
+   - The skill must tell an agent what to do, when to do it, what good output looks like, and what mistakes to avoid.
+   - References must be dense and navigable.
+   - Examples must demonstrate decisions or transformations, not decorative filler.
+   - If source material contained meaningful code snippets or worked examples, the generated skill must include adapted examples. Missing adapted examples is a failure to fix before finishing.
+   - Example coverage must match the source map: major code-facing source areas should point to concrete examples, not just prose references.
+   - Generated skills must include an artifact ownership/config policy section when they write or read project artifacts.
+   - Generated quality-gate skills must follow the `aif-gate-result` contract from `/aif-verify` references.
+   - In split mode, every child skill must have a distinct activation trigger. If two children would activate for the same request and tell the agent to do the same work, merge them before finishing.
+
+## Required Supporting Guidance
+
+Read these before generating or updating a distilled skill:
+- `references/DISTILLATION-PROTOCOL.md`
+- `references/OUTPUT-STRUCTURE.md`
+- `references/LARGE-MATERIALS.md`
+
+Use `examples/REQUESTS.md` for invocation patterns.
+
+## Artifact Ownership
+
+- Primary ownership: generated or updated skill packages under `{{skills_dir}}/<skill-name>/`, or multiple direct child skill packages under `{{skills_dir}}/<child-skill-name>/` in split mode.
+- Read-only context: `.ai-factory/config.yaml`, existing AI Factory context artifacts, and existing skill files except the selected target skill in update mode.
+- Config policy: config-aware for `language.ui`, `language.artifacts`, and `language.technical_terms` only. Do not write `config.yaml`.

package/skills/aif-distillation/examples/REQUESTS.md

@@ -0,0 +1,115 @@
+# Request Examples
+
+## Create a Skill from One Book
+
+```text
+/aif-distillation ./books/domain-driven-design.pdf --name ddd-practices
+```
+
+Expected output:
+
+- `{{skills_dir}}/ddd-practices/SKILL.md`
+- `{{skills_dir}}/ddd-practices/references/SOURCE-MAP.md`
+- dense references for tactical patterns, modeling workflow, and pitfalls
+- examples for aggregate boundaries and ubiquitous language checks
+
+## Create a Skill from Programming Material
+
+```text
+/aif-distillation ./books/code-quality.pdf --name code-quality-practices
+```
+
+Expected behavior:
+
+- inventory the source's code snippets and worked examples
+- create or update `examples/code-patterns.md` with original, compact code examples
+- add more focused example files when the material spans testing, debugging, refactoring, optimization, review, or integration patterns
+- map major code-facing source areas to concrete examples
+- include before/after snippets when the source teaches transformations
+- link the code examples from the target `SKILL.md`
+- avoid verbatim copying while preserving the programming lesson
+
+## Create Several Focused Skills from One Material Set
+
+```text
+/aif-distillation ./books/code-quality.pdf ./examples --split --name code-quality
+```
+
+Expected behavior:
+
+- infer focused child skills from distinct practices rather than creating one broad skill
+- use `code-quality` only as a naming seed when it helps; prefer clear child names such as `readability-refactor`, `naming-cleanup`, `condition-simplifier`, or `testability-pass`
+- write each child directly under `{{skills_dir}}/<child-skill-name>/`
+- give every child a distinct frontmatter description and activation trigger
+- include source attribution for every child
+- merge or skip candidates whose triggers overlap too much
+
+## Split by a Specific Strategy
+
+```text
+/aif-distillation ./docs/review-playbook --split-by workflow --name review
+```
+
+Expected behavior:
+
+- split by recurring actions an agent performs, not by arbitrary file count
+- create a boundary map before writing
+- update matching existing child skills when `--update` is also present
+- report created, updated, merged, and skipped candidates
+
+## Create a Skill from a Docs Folder
+
+```text
+/aif-distillation ./docs/internal-platform --name platform-operator
+```
+
+Expected behavior:
+
+- read current docs structure
+- save to `{{skills_dir}}/platform-operator/`
+- avoid duplicating existing examples
+- turn operational docs into agent instructions and checks
+- ignore hidden/config/sensitive files in the source folder unless the user explicitly opts in
+
+## Reject Unsafe Skill Names
+
+```text
+/aif-distillation ./docs --name ../foo
+/aif-distillation ./docs --name aif-review
+/aif-distillation ./docs --name .hidden
+/aif-distillation ./docs --name C:\temp\skill
+/aif-distillation ./docs --name clean/code
+```
+
+Expected behavior:
+
+- reject the request before writing files
+- explain that skill names must match `^[a-z0-9]+(?:-[a-z0-9]+)*$`
+- reserve `aif-*` names unless the user explicitly says they are developing AI Factory itself
+- confirm the resolved target path would stay under `{{skills_dir}}`
+
+## Update an Existing Skill
+
+```text
+/aif-distillation ./new-material ./examples --name platform-operator --update
+```
+
+Expected behavior:
+
+- compare existing references and examples
+- update matching files in place
+- add only missing topics
+- report changed files
+
+## Create a Skill from URLs
+
+```text
+/aif-distillation https://example.com/guide https://example.com/reference --name example-api
+```
+
+Expected behavior:
+
+- fetch the pages
+- follow only critical sub-pages
+- source-map all URLs used
+- summarize rules and examples without long quoted passages

package/skills/aif-distillation/references/DISTILLATION-PROTOCOL.md

@@ -0,0 +1,181 @@
+# Distillation Protocol
+
+Use this protocol to convert source material into a reusable Agent Skill.
+
+## 1. Source Intake
+
+Create a source inventory:
+
+| Field | Meaning |
+|-------|---------|
+| Source | URL or local path |
+| Type | book, docs, code, policy, tutorial, paper, notes |
+| Scope | what the material covers |
+| Signal | why it matters for the target skill |
+| Gaps | missing context that may require another source |
+
+For folders, group files by topic before reading deeply. For books, read the table of contents first, then sample each major part before deep extraction.
+
+## 2. Extraction
+
+Extract only material that can drive agent behavior:
+
+- concepts that change decisions
+- named techniques, workflows, and checklists
+- constraints and preconditions
+- quality bars and failure modes
+- examples that teach a reusable pattern
+- code snippets, command examples, and worked examples that demonstrate a reusable decision or transformation
+- terminology that prevents misunderstanding
+
+For code-heavy sources, also build an example inventory:
+
+| Source topic | Example type | Distilled example target |
+|--------------|--------------|--------------------------|
+| <topic> | snippet, before/after, test, debug trace, decision table | <examples file or "skip: reason"> |
+
+This inventory is a planning tool. It does not need to be shipped verbatim, but
+the final examples must visibly cover the major code-facing topics from it.
+
+Skip:
+
+- praise, marketing, introductions, and repetition
+- historical context unless it changes practice
+- examples that do not generalize
+- long verbatim passages
+
+## 3. Synthesis
+
+Transform extracted material into:
+
+- **Rules:** direct instructions an agent can follow
+- **Heuristics:** judgment calls with conditions
+- **Workflow:** ordered steps with inputs and outputs
+- **Checklists:** gates for quality and completeness
+- **Examples:** compact input/output or before/after cases
+- **Pitfalls:** common mistakes and how to detect them
+
+For programming material, do not stop at prose rules. If the source uses code
+examples to teach a practice, create original snippets that preserve the lesson
+without copying the source. Prefer small before/after examples, named code
+patterns, decision tables, and test/refactoring examples that can be applied in
+the target ecosystem. If the source examples are language-specific and the user
+does not request a different language, keep the examples in that ecosystem.
+
+For broad programming books or documentation sets, do not compress example
+coverage into a handful of generic snippets. Cover the major example families:
+abstraction/type design, routine/function shape, data/naming, control flow,
+defensive boundaries, tests, debugging, refactoring, performance, comments, and
+integration when the source covers them. A topic can be skipped only with a
+specific reason, such as "covered by checklist only; no reusable code pattern."
+
+When source material conflicts, keep both positions only if the context differs. Otherwise choose the stronger rule and note the reason in a reference.
+
+## 4. Skill Design
+
+Before writing, answer:
+
+1. What task should trigger this skill?
+2. Who benefits from it?
+3. What should the agent produce?
+4. What source-derived checks define success?
+5. Which details belong in references instead of `SKILL.md`?
+
+The target `SKILL.md` should fit in one screen when possible. It is the router and operating loop, not the knowledge base.
+
+## 5. Split-Skill Design
+
+Use this section only when the user passes `--split` or `--split-by <strategy>`.
+
+Split source material into multiple skills when the material contains separate
+capabilities that should activate on different user requests. A split set should
+feel like a small toolkit of focused passes, not a chopped-up book summary.
+
+Supported strategies:
+
+| Strategy | Use when | Boundary signal |
+|----------|----------|-----------------|
+| `auto` | the user wants several skills but did not prescribe boundaries | strongest distinct triggers from topics, workflows, examples, and target users |
+| `topic` | the source has clean domain or chapter boundaries | each topic produces different decisions or checks |
+| `workflow` | the source teaches multiple actions | each action has a different input, output, or quality gate |
+| `audience` | the source serves different roles or project contexts | each role/context needs different operating instructions |
+
+Before writing split skills, create a boundary map:
+
+| Child skill | Trigger | Source topics | References/examples | Merge risk |
+|-------------|---------|---------------|---------------------|------------|
+| <name> | <when it should activate> | <topics> | <files> | low/medium/high |
+
+Merge or drop a child candidate when:
+
+- its trigger overlaps another candidate without a meaningful workflow
+  difference
+- it would contain only generic advice
+- it depends on another child for basic operation
+- it has no source-derived checks or examples
+
+For broad code-quality material, good split candidates are often operation
+passes such as readability refactoring, naming cleanup, condition
+simplification, magic value extraction, exception-flow review, testability, and
+framework-specific review. These names are examples, not required output.
+
+Every child skill must include its own source attribution. For small children,
+`references/SOURCE-MAP.md` may be the only reference; for larger children, add
+focused references and examples.
+
+## 6. Existing-File Merge
+
+Before creating any new reference or example:
+
+1. List existing `references/`, `examples/`, `scripts/`, and `templates/`.
+2. Compare intended topic names with existing file names and headings.
+3. Update matching files when the new material fills gaps.
+4. For code-heavy material, look for an existing code examples file such as
+   `code-patterns.md`, `before-after.md`, or a topic-specific examples file and
+   update it before creating a new one.
+5. Create a new file only for a genuinely new topic.
+6. Keep stable filenames so future updates do not fragment the skill.
+
+For book-scale programming material, prefer multiple focused example files over
+one shallow sampler, for example:
+
+- `code-patterns.md` for local construction patterns
+- `testing-debugging.md` for test and debugging examples
+- `refactoring-optimization.md` for safe change and measurement examples
+- `review-examples.md` for review findings and corrections
+
+In split mode, perform this merge check across sibling skills too. A proposed
+child should update an existing matching skill when the existing frontmatter
+description and workflow already cover the same capability.
+
+## 7. Traceability
+
+Every distilled skill should include a source map in a reference:
+
+```markdown
+## Source Map
+
+| Source | Used for |
+|--------|----------|
+| <path-or-url> | <principles, workflow, examples, checks> |
+```
+
+Do not imply that every rule is a direct quote. Distillation is synthesis; source maps explain provenance.
+
+## 8. Quality Gate
+
+Before finishing, check:
+
+- `SKILL.md` explains what and when in frontmatter.
+- `SKILL.md` stays concise and points to references/examples.
+- References contain the dense knowledge.
+- Examples are actionable and source-derived.
+- Code-heavy sources have adapted code snippets in `examples/`; missing snippets
+  are a blocking quality failure.
+- Example coverage maps to the source areas. If references mention many
+  code-facing topics but examples cover only a few, the skill is incomplete.
+- Existing references/examples were updated instead of duplicated.
+- Split mode only: each child skill has a distinct trigger, direct `{{skills_dir}}/<child>/` location, source attribution, and enough references/examples to operate independently.
+- Split mode only: no generated child is a near-duplicate of another generated or existing sibling skill.
+- Temporary extraction files were removed.
+- No long copyrighted passages were copied.