ai-factory 2.13.0 → 2.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-factory",
-  "version": "2.13.0",
+  "version": "2.13.2",
   "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>] [--path <directory>] [--update] [--redact-source-map] [--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:
@@ -31,7 +32,7 @@ If config.yaml doesn't exist, use defaults:
 
 **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.
+Treat skill-context rules as project-level overrides for this skill. They apply to all generated skill files, references, examples, source-map policy, and final reports.
 
 ## Inputs
 
@@ -40,17 +41,32 @@ Accept `$ARGUMENTS` as one or more:
 - local directories
 - URLs
 - optional `--name <skill-name>`
+- optional `--path <directory>` to save generated skill package directories under a custom output root instead of `{{skills_dir}}`
 - optional `--update` to improve an existing skill instead of creating a duplicate
+- optional `--redact-source-map` to skip generated source-map files and sections entirely, so exact source titles, URLs, local paths, repository paths, and link reference definitions are not written to output
+- 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 user goals, triggers, workflows, source topics, and use cases
+  - `goal`: split by user goals or jobs-to-be-done, regardless of domain
+  - `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`.
+If the target skill name is missing, derive a concise, general, lowercase-hyphenated name from the material topic or user goal, such as `clean-code-style`, `api-design-rules`, `decision-making`, `writing-feedback`, or `meeting-facilitation`.
 
 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.
+- Resolve the output root: `--path <directory>` when present, otherwise `{{skills_dir}}`.
+- Treat relative `--path` values as relative to the current working directory. Create the output root if it does not exist; reject it if it resolves to an existing file.
+- Resolve the final destination path and confirm it is inside the resolved output root 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: `<output-root>/<skill-name>/`, where `<output-root>` is `{{skills_dir}}` unless `--path` is present.
+
+Default destination for split mode: `<output-root>/<prefix>-<child-scope>/` for each generated child skill. Every split child name must share one namespace prefix to prevent collisions with existing skills. Use `--name` as the preferred prefix when present; otherwise derive a concise prefix from the book title or primary material title. If `--redact-source-map` is present and the exact source title should not be exposed, use `--name` as the public namespace or derive a neutral topic prefix.
+
+Do not save distilled skills into the package `skills/` directory unless the user is explicitly developing AI Factory itself.
 
 ## Workflow
 
@@ -66,29 +82,47 @@ 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, resolve one shared namespace prefix before writing the boundary map. Use `--name` when present; otherwise use a normalized book/material title. Every proposed child name must start with `<prefix>-`.
+   - In split mode, create a skill boundary map before writing: proposed prefixed skill name, user-facing job, trigger description, owned source topics, references/examples needed, and overlap risks.
+   - Prefer split mode when the material contains independent goals that should trigger separately, such as reviewing, planning, diagnosing, rewriting, teaching, deciding, testing, facilitating, auditing, or troubleshooting.
+   - Name split children by the user goal or job-to-be-done, not by an abstract source theme. Choose the goal taxonomy from the material's domain: for software this may be `refactoring-review`, `test-design`, or `framework-fit-review`; for writing this may be `argument-edit` or `style-review`; for operations this may be `incident-triage` or `runbook-review`; for management this may be `decision-brief` or `stakeholder-analysis`; for learning this may be `concept-coach` or `practice-drill`.
+   - Avoid vague lifecycle or chapter names such as `framework-evolution`, `principles`, `philosophy`, `chapter-4`, `mindset`, or `overview` unless that exact name is the user's requested public taxonomy.
+   - 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, and relevant references/examples. If `--redact-source-map` is absent, include its own source map; if present, do not create `references/SOURCE-MAP.md` or a source-map section.
+
+4. Design the target skill package.
    - Keep target `SKILL.md` focused on purpose, triggers, and workflow.
+   - Make the generated skill self-explanatory from its directory name and frontmatter. The description must start with an action verb and say what the skill reviews, improves, generates, or checks.
+   - Near the top of every generated `SKILL.md`, answer in plain language: what this skill does, when to use it, and what output it should produce. A user should not need to inspect the source material to understand why the skill exists.
    - 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.
+   - Resolve `<output-root>` from `--path` or `{{skills_dir}}` before writing. Treat `--path` as a parent directory for generated skill packages, not as the skill package name.
+   - In single-skill mode, save the package under `<output-root>/<skill-name>/` using the chosen concise name.
+   - In split mode, save each child package directly under `<output-root>/<prefix>-<child-scope>/`. Do not drop the shared prefix even when the child scope is clear on its own.
+   - When `--redact-source-map` is present, do not create `references/SOURCE-MAP.md`, do not create a "Source Map" section in any generated file, and remove any empty `SOURCE-MAP.md` accidentally created during drafting. In `--update` mode, leave an existing non-empty `SOURCE-MAP.md` unchanged unless the user explicitly asks to remove or rewrite it.
    - 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 `<output-root>` 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.
+   - The name and description must be invocation-ready. If a user would ask "what does this skill actually do?", rename it or rewrite the trigger before finishing.
    - 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.
+   - Example coverage must match source coverage: when `--redact-source-map` is absent, record this in the source map; when present, validate coverage internally without writing source-map files or sections.
    - 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 +135,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 `<output-root>/<skill-name>/`, or multiple direct child skill packages under `<output-root>/<prefix>-<child-scope>/` in split mode. `<output-root>` is `{{skills_dir}}` unless the user passes `--path <directory>`.
 - 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,88 @@ 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` as the required shared namespace prefix
+- prefer clear child names such as `code-quality-readability-refactor`, `code-quality-naming-cleanup`, `code-quality-condition-simplifier`, or `code-quality-testability-pass`
+- write each child directly under `{{skills_dir}}/<prefix>-<child-scope>/`
+- give every child a distinct frontmatter description and activation trigger
+- include source attribution for every child unless `--redact-source-map` is present
+- merge or skip candidates whose triggers overlap too much
+
+## Save to a Custom Output Root
+
+```text
+/aif-distillation ./books/domain-driven-design.pdf --name ddd-practices --path ./distilled-skills
+```
+
+Expected output:
+
+- `./distilled-skills/ddd-practices/SKILL.md`
+- `./distilled-skills/ddd-practices/references/SOURCE-MAP.md`
+- no writes to the current agent `{{skills_dir}}`
+- resolved destination stays inside the resolved `--path` output root
+
+## Split into a Custom Output Root
+
+```text
+/aif-distillation ./books/code-quality.pdf --split --name code-quality --path ./distilled-skills
+```
+
+Expected behavior:
+
+- create direct child package directories under `./distilled-skills/`
+- name every child with the shared `code-quality-` prefix
+- do not create a parent `code-quality/` wrapper directory unless explicitly requested as an index/router skill
+
+## 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
+- name every child with the shared `review-` prefix, such as `review-triage` or `review-findings`
+- create a boundary map before writing
+- update matching existing child skills when `--update` is also present
+- report created, updated, merged, and skipped candidates
+
+## Split Non-Code Material by User Goals
+
+```text
+/aif-distillation ./books/decision-making.pdf --split-by goal --name decisions
+```
+
+Expected behavior:
+
+- split by jobs the user wants help with, not by chapter titles
+- create names such as `decisions-decision-brief`, `decisions-risk-review`, or `decisions-stakeholder-analysis`
+- make every child explain what it does, when to use it, and what output it should produce
+- avoid vague children such as `decisions-principles`, `decisions-mindset`, or `decisions-chapter-2`
+
+## Redact Source Map Paths and Links
+
+```text
+/aif-distillation ./books/internal-review-guide.pdf --name review-guide --redact-source-map
+```
+
+Expected behavior:
+
+- generate the skill normally
+- do not create `references/SOURCE-MAP.md`
+- do not create a "Source Map" section in `SKILL.md` or any reference file
+- omit exact book titles, URLs, local paths, repository paths, filenames, and link reference definitions from generated files
+- keep source coverage only in private working notes while still producing useful distilled instructions, references, and examples
+
 ## Create a Skill from a Docs Folder
 
 ```text
@@ -58,7 +140,7 @@ 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}}`
+- confirm the resolved target path would stay under the resolved output root (`{{skills_dir}}` by default, or `--path` when present)
 
 ## Update an Existing Skill
 
@@ -83,5 +165,5 @@ Expected behavior:
 
 - fetch the pages
 - follow only critical sub-pages
-- source-map all URLs used
+- source-map all URLs used unless `--redact-source-map` is present; with redaction, do not create `SOURCE-MAP.md`
 - summarize rules and examples without long quoted passages

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

@@ -16,6 +16,12 @@ Create a source inventory:
 
 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.
 
+When the user passes `--redact-source-map`, keep any exact URLs, local paths,
+repository paths, and source titles only in your private working inventory.
+Generated skill files must use neutral source labels such as `Source A`,
+`Book section 1`, or `Internal guide: authentication`, while preserving the
+type, scope, and usage of each source.
+
 ## 2. Extraction
 
 Extract only material that can drive agent behavior:
@@ -83,7 +89,74 @@ 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.
+If `--path <directory>` is present, create the split set under that output root
+instead of the current agent `{{skills_dir}}`.
+
+Supported strategies:
+
+| Strategy | Use when | Boundary signal |
+|----------|----------|-----------------|
+| `auto` | the user wants several skills but did not prescribe boundaries | strongest distinct goals, triggers, workflows, examples, and target users |
+| `goal` | the material supports several different jobs-to-be-done | each child helps the user accomplish a different outcome |
+| `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 | User goal | Trigger | Source topics | References/examples | Merge risk |
+|-------------|-----------|---------|---------------|---------------------|------------|
+| <name> | <outcome it helps achieve> | <when it should activate> | <topics> | <files> | low/medium/high |
+
+First resolve a shared split namespace prefix:
+
+- use `--name` when the user supplied it
+- otherwise derive the prefix from the book title or primary material title
+- if source-map redaction is requested and the real title should stay private,
+  use a neutral topic prefix instead of the exact title
+- validate the prefix with the same skill-name rules as ordinary skills
+- every generated child name must start with `<prefix>-`
+
+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.
+
+For non-code material, use the same goal-first rule. Examples:
+
+- writing or communication: `argument-edit`, `style-review`, `message-critique`
+- strategy or management: `decision-brief`, `stakeholder-analysis`, `risk-review`
+- operations or support: `incident-triage`, `runbook-review`, `escalation-plan`
+- learning material: `concept-explainer`, `practice-drill`, `understanding-check`
+- research material: `evidence-synthesis`, `claim-audit`, `literature-map`
+
+Avoid source-theme children with unclear invocation intent.
+If a candidate name makes a user ask "what does this do?", rename it around the
+goal and expected output.
+
+Every child skill must include its own source attribution unless
+`--redact-source-map` is present. For small non-redacted children,
+`references/SOURCE-MAP.md` may be the only reference; for larger children, add
+focused references and examples. In redaction mode, do not create
+`references/SOURCE-MAP.md`; keep source coverage in the private working
+inventory and ship only the distilled instructions, references, and examples.
+
+## 6. Existing-File Merge
 
 Before creating any new reference or example:
 
@@ -104,9 +177,14 @@ 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.
 
-Every distilled skill should include a source map in a reference:
+## 7. Traceability
+
+Every distilled skill should include a source map in a reference unless
+`--redact-source-map` is present:
 
 ```markdown
 ## Source Map
@@ -116,9 +194,18 @@ Every distilled skill should include a source map in a reference:
 | <path-or-url> | <principles, workflow, examples, checks> |
 ```
 
-Do not imply that every rule is a direct quote. Distillation is synthesis; source maps explain provenance.
+When `--redact-source-map` is present, do not create `references/SOURCE-MAP.md`
+and do not add a "Source Map" section to any generated file. Do not write link
+reference definitions, raw path fragments, repository paths, filenames that
+reveal the source, exact URLs, or exact book/document titles anywhere as source
+attribution. If a draft creates an empty `SOURCE-MAP.md`, remove it before
+finishing. In `--update` mode, leave an existing non-empty `SOURCE-MAP.md`
+unchanged unless the user explicitly asks to remove or rewrite it.
+
+For non-redacted source maps, 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 +218,8 @@ 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 `<output-root>/<prefix>-<child>/` location, source attribution when not redacted, no `SOURCE-MAP.md` when redacted, and enough references/examples to operate independently.
+- Split mode only: all generated child names share the same prefix derived from `--name`, the book title, or a neutral material namespace.
+- 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/LARGE-MATERIALS.md

@@ -28,6 +28,11 @@ Optional flags:
 
 Read `source-index.md` first. Then read only the chunks needed for each section of the target skill.
 
+When `--redact-source-map` is present, treat `source-index.md` as a private
+working index only. Do not copy its raw URLs, local paths, filenames, or exact
+source titles into generated files. Do not create `references/SOURCE-MAP.md`
+for redacted output.
+
 ## Chunking Strategy
 
 Use this order:

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

@@ -5,10 +5,10 @@ Use this structure for skills created by `aif-distillation`.
 ## Target Package
 
 ```text
-{{skills_dir}}/<skill-name>/
+<output-root>/<skill-name>/
 ├── SKILL.md
 ├── references/
-│   ├── SOURCE-MAP.md
+│   ├── SOURCE-MAP.md   # omit when --redact-source-map is present
 │   ├── CORE-PRINCIPLES.md
 │   ├── WORKFLOW.md
 │   └── CHECKLISTS.md
@@ -27,19 +27,86 @@ 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
+<output-root>/
+├── <prefix>-<child-skill-a>/
+│   ├── SKILL.md
+│   ├── references/
+│   │   ├── SOURCE-MAP.md   # omit when --redact-source-map is present
+│   │   └── <focused-reference>.md
+│   └── examples/
+│       └── <focused-examples>.md
+├── <prefix>-<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 the output root when that root is an
+agent skills directory.
+
+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`
+- a distinct non-code goal, such as `argument-edit`, `decision-brief`,
+  `incident-triage`, `practice-drill`, or `risk-review`
+
+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:
+Save the distilled skill in the configured skills directory of the currently active agent by default:
 
 ```text
 {{skills_dir}}/<skill-name>/
 ```
 
 `{{skills_dir}}` is resolved by AI Factory for the active agent installation.
+If the user passes `--path <directory>`, use that directory as the output root
+instead:
+
+```text
+<directory>/<skill-name>/
+```
+
+`--path` is a parent output directory for generated skill package directories,
+not the skill package name itself. Resolve relative `--path` values from the
+current working directory. Create the output root if it does not exist; reject
+it if it resolves to an existing file. For a single exact destination, the user
+should pass `--path <parent-dir> --name <directory-name>`.
 
 Do not write distilled output into AI Factory's package `skills/` directory unless the task is explicitly to add a built-in AI Factory skill.
 
-Before writing, resolve and canonicalize the final destination path. It must stay inside the resolved `{{skills_dir}}` directory.
+Before writing, resolve and canonicalize the output root and final destination
+path. The final destination must stay inside the resolved output root. When
+`--path` is absent, the output root is `{{skills_dir}}`.
+
+For split mode, apply this same validation to every generated child skill path.
+Every generated child name must use one shared namespace prefix:
+
+- use `--name <skill-name>` as the prefix when supplied
+- otherwise derive a concise prefix from the book title or primary material title
+- when source-map redaction is requested, avoid exposing a private title and use
+  `--name` or a neutral material/topic prefix instead
+- write children as `<output-root>/<prefix>-<child-scope>/`
+- do not create unprefixed split children, even when the child scope reads well
+  by itself
 
 ## Naming
 
@@ -57,6 +124,10 @@ Good:
 - `domain-modeling`
 - `api-design-rules`
 - `incident-review`
+- `argument-edit`
+- `decision-brief`
+- `practice-drill`
+- `risk-review`
 
 Avoid:
 
@@ -66,6 +137,18 @@ 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 start with the same resolved namespace prefix plus `-`
+- 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
+- the suffix after the prefix should describe the user goal and expected action, not provenance
+- avoid double-prefixing names when a candidate suffix already contains the prefix
+- avoid abstract source-theme suffixes such as `principles`, `philosophy`,
+  `evolution`, `mindset`, or `chapter-3` unless the user explicitly requested
+  that taxonomy
+
 ## SKILL.md Rules
 
 `SKILL.md` should contain:
@@ -95,7 +178,7 @@ For AI Factory-style skills, also include:
 
 | File | Purpose |
 |------|---------|
-| `SOURCE-MAP.md` | Sources, coverage, and attribution |
+| `SOURCE-MAP.md` | Sources, coverage, and attribution; omit entirely when `--redact-source-map` is present |
 | `CORE-PRINCIPLES.md` | Dense distilled concepts and rules |
 | `WORKFLOW.md` | Step-by-step operating procedure |
 | `CHECKLISTS.md` | Review gates and quality criteria |
@@ -104,6 +187,15 @@ For AI Factory-style skills, also include:
 
 Prefer stable, obvious filenames over clever names.
 
+When `--redact-source-map` is present:
+
+- do not create `references/SOURCE-MAP.md`
+- do not create a "Source Map" section in `SKILL.md` or any reference file
+- remove any empty `SOURCE-MAP.md` created while drafting
+- in `--update` mode, leave an existing non-empty `SOURCE-MAP.md` unchanged
+  unless the user explicitly asks to remove or rewrite it
+- keep source coverage checks in the private working notes only
+
 ## Example File Roles
 
 Examples should show how to apply the distilled knowledge:
@@ -139,6 +231,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: