ai-factory 2.13.0 → 2.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-factory",
-  "version": "2.13.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-distillation/SKILL.md

@@ -2,9 +2,10 @@
 name: aif-distillation
 description: >-
   Distill books, documents, folders, or URLs into compact, practical Agent Skills.
-  Use when source material should become a reusable skill package with a concise
-  SKILL.md plus detailed references and examples.
-argument-hint: "<path|url> [path|url...] [--name <skill-name>] [--update]"
+  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:
@@ -41,6 +42,12 @@ Accept `$ARGUMENTS` as one or more:
 - 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`.
 
@@ -50,7 +57,11 @@ Before any write, validate the final target skill name:
 - 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: `{{skills_dir}}/<skill-name>/` for the current agent. Do not save distilled skills into the package `skills/` directory unless the user is explicitly developing AI Factory itself.
+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
 
@@ -66,22 +77,31 @@ Default destination: `{{skills_dir}}/<skill-name>/` for the current agent. Do no
    - 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. Design the target skill package.
+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.
-   - Save the package under `{{skills_dir}}/<skill-name>/` using the chosen concise name.
+   - 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.
 
-4. Check existing content before writing.
+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.
 
-5. Validate usefulness.
+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.
@@ -89,6 +109,7 @@ Default destination: `{{skills_dir}}/<skill-name>/` for the current agent. Do no
    - 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
 
@@ -101,6 +122,6 @@ Use `examples/REQUESTS.md` for invocation patterns.
 
 ## Artifact Ownership
 
-- Primary ownership: generated or updated skill packages under `{{skills_dir}}/<skill-name>/`.
+- 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

@@ -29,6 +29,34 @@ Expected behavior:
 - 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

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

@@ -83,7 +83,47 @@ Before writing, answer:
 
 The target `SKILL.md` should fit in one screen when possible. It is the router and operating loop, not the knowledge base.
 
-## 5. Existing-File Merge
+## 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:
 
@@ -104,7 +144,11 @@ one shallow sampler, for example:
 - `refactoring-optimization.md` for safe change and measurement examples
 - `review-examples.md` for review findings and corrections
 
-## 6. Traceability
+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:
 
@@ -118,7 +162,7 @@ Every distilled skill should include a source map in a reference:
 
 Do not imply that every rule is a direct quote. Distillation is synthesis; source maps explain provenance.
 
-## 7. Quality Gate
+## 8. Quality Gate
 
 Before finishing, check:
 
@@ -131,5 +175,7 @@ Before finishing, check:
 - 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.

package/skills/aif-distillation/references/OUTPUT-STRUCTURE.md

@@ -27,6 +27,45 @@ For broad programming material, use enough example files to cover the major
 source topics. Do not create a single `code-patterns.md` that only samples a few
 topics while the references claim broad code coverage.
 
+## Split-Skill Target Packages
+
+When the user passes `--split` or `--split-by <strategy>`, create multiple
+focused skill packages instead of one broad package:
+
+```text
+{{skills_dir}}/
+├── <child-skill-a>/
+│   ├── SKILL.md
+│   ├── references/
+│   │   ├── SOURCE-MAP.md
+│   │   └── <focused-reference>.md
+│   └── examples/
+│       └── <focused-examples>.md
+├── <child-skill-b>/
+│   └── SKILL.md
+└── <optional-index-skill>/
+    └── SKILL.md
+```
+
+Do not create a parent directory that contains child skills. Agent runtimes
+discover skills as direct children of `{{skills_dir}}`.
+
+Create an optional index/router skill only when it is genuinely useful, for
+example when the split set is large or users need a single command-style entry
+point. The index skill should list the child skills and when to use each one; it
+must not duplicate their references.
+
+Each child skill should be narrow enough to trigger independently. Good split
+boundaries include:
+
+- a distinct code review pass, such as `naming-cleanup` or `testability-pass`
+- a distinct refactoring operation, such as `early-return-simplifier`
+- a distinct framework or runtime practice, such as `laravel-query-boundaries`
+- a distinct writing or analysis workflow, such as `comments-curator`
+
+Avoid split boundaries based only on source chapter titles when the resulting
+skills would have the same trigger and workflow.
+
 ## Destination
 
 Save the distilled skill in the configured skills directory of the currently active agent:
@@ -41,6 +80,11 @@ Do not write distilled output into AI Factory's package `skills/` directory unle
 
 Before writing, resolve and canonicalize the final destination path. It must stay inside the resolved `{{skills_dir}}` directory.
 
+For split mode, apply this same validation to every generated child skill path.
+If `--name <seed>` is supplied, use it as a naming seed or short prefix only
+when it improves discoverability. Prefer clear standalone names over repetitive
+prefixes.
+
 ## Naming
 
 Choose a concise, general name that matches the distilled practice, not just the exact source title.
@@ -66,6 +110,14 @@ Avoid:
 - vague names like `notes`, `reference`, or `book-summary`
 - reserved or unsafe names like `aif-review`, `../foo`, `.hidden`, `C:\temp\skill`, or `clean/code`
 
+In split mode, generate a name list before writing and check it as a set:
+
+- every name must pass the same validation rules
+- no name may collide with another generated child
+- no generated child may shadow a built-in `aif-*` skill
+- names should describe activation scope, not provenance
+- when multiple child names share a long prefix, remove the prefix unless it is needed to prevent ambiguity
+
 ## SKILL.md Rules
 
 `SKILL.md` should contain:
@@ -139,6 +191,15 @@ When `--update` is present:
 5. Add new files only for new topics.
 6. Report what changed and what was intentionally left untouched.
 
+In split mode with `--update`, treat every proposed child skill independently:
+
+1. Build the child skill boundary map.
+2. Match each proposed child to existing skills by name, frontmatter
+   description, and trigger/workflow overlap.
+3. Update matched skills in place.
+4. Create new child skills only for uncovered capabilities.
+5. Report merged, created, skipped, and renamed candidates.
+
 ## Ownership and Context-Gate Alignment
 
 When distilling material into an AI Factory workflow or quality skill: