ai-factory 2.3.0 → 2.4.0

package/README.md

@@ -144,6 +144,7 @@ AI Factory can generate and maintain your project docs with a single command:
 | [Development Workflow](docs/workflow.md) | Workflow diagram, when to use what, spec-driven approach |
 | [Reflex Loop](docs/loop.md) | Iterative generate → evaluate → critique → refine workflow |
 | [Core Skills](docs/skills.md) | All slash commands — explore, plan, fix, implement, evolve, docs, and more |
+| [Skill Evolution](docs/evolve.md) | How /aif-fix patches feed into /aif-evolve to generate smarter skill rules |
 | [Plan Files](docs/plan-files.md) | Plan files, self-improvement patches, skill acquisition |
 | [Security](docs/security.md) | Two-level security scanning for external skills |
 | [Extensions](docs/extensions.md) | Writing and installing extensions — commands, injections, MCP, agents |

package/package.json

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

package/skills/aif/SKILL.md

@@ -56,6 +56,29 @@ Read the SKILL.md and all supporting files. Ask: "Does every instruction serve t
 
 ---
 
+### Project Context
+
+**Read `.ai-factory/skill-context/aif/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including DESCRIPTION.md,
+  AGENTS.md, and MCP configuration. The templates in this SKILL.md are **base structures**. If a
+  skill-context rule says "DESCRIPTION.md MUST include X" or "AGENTS.md MUST have section Y" —
+  you MUST augment the templates accordingly. Generating artifacts that violate skill-context rules
+  is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ## Skill Acquisition Strategy
 
 **Always search skills.sh before generating. Always scan before trusting.**
@@ -395,6 +418,12 @@ Install skills, configure MCP, generate `AGENTS.md`, and generate architecture d
 4. **MCP in .mcp.json** — Project-level (agent reads MCP from `.mcp.json`, not `settings.local.json`)
 5. **Remind about env vars** — For MCP that need credentials
 
+## Artifact Ownership
+
+- Primary ownership in this command: `.ai-factory/DESCRIPTION.md`, setup-time `AGENTS.md`, installed skills, and MCP configuration.
+- Delegated ownership: invoke `/aif-architecture` to create/update `.ai-factory/ARCHITECTURE.md`.
+- Read-only context in this command by default: `.ai-factory/ROADMAP.md`, `.ai-factory/RULES.md`, `.ai-factory/RESEARCH.md`, and plan files.
+
 ## CRITICAL: Do NOT Implement
 
 **This skill ONLY sets up context (skills + MCP). It does NOT implement the project.**

package/skills/aif-architecture/SKILL.md

@@ -33,6 +33,26 @@ Run /aif first to set up project context, or describe your project manually:
 
 Allow standalone usage — if user provides manual input, use that instead.
 
+**Read `.ai-factory/skill-context/aif-architecture/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the
+  ARCHITECTURE.md template. The template in this SKILL.md is a **base structure**. If a skill-context
+  rule says "architecture doc MUST include X" or "MUST cover section Y" — you MUST augment the
+  template accordingly. Generating ARCHITECTURE.md that violates skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ### Step 1: Analyze & Recommend
 
 Based on project context, evaluate against the decision matrix and recommend an architecture:
@@ -165,6 +185,12 @@ Key rules:
 All workflow skills (/aif-plan, /aif-implement) will now follow these architecture guidelines.
 ```
 
+## Artifact Ownership
+
+- Primary ownership: `.ai-factory/ARCHITECTURE.md`.
+- Allowed companion updates: architecture pointer in `.ai-factory/DESCRIPTION.md`, architecture row in `AGENTS.md` context table.
+- Read-only context: roadmap, rules, research, and plan artifacts unless user explicitly requests otherwise.
+
 ---
 
 ## Knowledge Base

package/skills/aif-best-practices/SKILL.md

@@ -12,6 +12,26 @@ Universal code quality guidelines applicable to any language or framework.
 
 **Context:** If `.ai-factory/ARCHITECTURE.md` exists, follow its folder structure, dependency rules, and module boundaries alongside these guidelines.
 
+**Read `.ai-factory/skill-context/aif-best-practices/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the
+  recommendations, examples, and checklists you present. If a skill-context rule says "best practices
+  MUST prioritize X" or "examples MUST follow convention Y" — you MUST comply. Presenting guidance
+  that contradicts skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ## Quick Reference
 
 - `/aif-best-practices` — Full overview

package/skills/aif-build-automation/SKILL.md

@@ -33,6 +33,26 @@ Read .ai-factory/DESCRIPTION.md
 
 Store the project context (tech stack, framework, architecture) for use in later steps. If the file doesn't exist, that's fine — we'll detect everything in Step 2.
 
+**Read `.ai-factory/skill-context/aif-build-automation/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the generated
+  build files (Makefile, Taskfile, justfile, magefile). Templates in this skill are **base structures**.
+  If a skill-context rule says "build file MUST include target X" or "MUST follow convention Y" —
+  you MUST comply. Generating build automation that violates skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ---
 
 ## Step 1: Detect Existing Build Files & Determine Mode

package/skills/aif-ci/SKILL.md

@@ -34,6 +34,26 @@ Read .ai-factory/DESCRIPTION.md
 
 Store project context for later steps. If absent, Step 2 detects everything.
 
+**Read `.ai-factory/skill-context/aif-ci/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including generated
+  CI workflow files and audit reports. Templates in this skill are **base structures**. If a
+  skill-context rule says "CI MUST include step X" or "workflow MUST have job Y" — you MUST augment
+  the templates accordingly. Generating CI config that violates skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ---
 
 ## Step 1: Detect Existing CI & Determine Mode

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: Bash(git *)
+allowed-tools: Read Bash(git *) AskUserQuestion Questions
 disable-model-invocation: false
 ---
 
@@ -12,12 +12,38 @@ Generate commit messages following the [Conventional Commits](https://www.conven
 
 ## Workflow
 
+**Read `.ai-factory/skill-context/aif-commit/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the commit
+  message format and conventions. If a skill-context rule says "commits MUST follow format X"
+  or "message MUST include Y" — you MUST comply. Generating a commit message that violates
+  skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 1. **Analyze Changes**
    - Run `git status` to see staged files
    - Run `git diff --cached` to see staged changes
    - If nothing staged, show warning and suggest staging
 
-2. **Determine Commit Type**
+2. **Run Context Gates (Read-Only)**
+   - Check `.ai-factory/ARCHITECTURE.md` and `.ai-factory/DESCRIPTION.md` (if present) to catch obvious scope/boundary drift
+   - Check `.ai-factory/RULES.md` and `.ai-factory/ROADMAP.md` (if present) to catch rule and milestone alignment issues
+   - Missing optional files (`ROADMAP.md`, `RULES.md`) are `WARN`, not blockers
+   - Never modify context artifacts from this command
+
+3. **Determine Commit Type**
    - `feat`: New feature
    - `fix`: Bug fix
    - `docs`: Documentation only
@@ -29,12 +55,12 @@ Generate commit messages following the [Conventional Commits](https://www.conven
    - `ci`: CI configuration
    - `chore`: Maintenance tasks
 
-3. **Identify Scope**
+4. **Identify Scope**
    - From file paths (e.g., `src/auth/` → `auth`)
    - From argument if provided
    - Optional - omit if changes span multiple areas
 
-4. **Generate Message**
+5. **Generate Message**
    - Keep subject line under 72 characters
    - Use imperative mood ("add" not "added")
    - Don't capitalize first letter after type
@@ -80,16 +106,18 @@ When invoked:
 
 1. Check for staged changes
 2. Analyze the diff content
-3. Propose a commit message
-4. Ask for confirmation or modifications
-5. Execute `git commit` with the message
-6. After a successful commit, offer to push:
+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. Ask for confirmation or modifications
+7. Execute `git commit` with the message
+8. After a successful commit, offer to push:
    - Show branch/ahead status: `git status -sb`
    - If the branch has no upstream, use: `git push -u origin <branch>`
    - Otherwise: `git push`
    - User choice:
-     - [ ] Push now
-     - [ ] Skip push
+      - [ ] Push now
+      - [ ] Skip push
 
 If argument provided (e.g., `/aif-commit auth`):
 - Use it as the scope
@@ -99,6 +127,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 `.ai-factory/ARCHITECTURE.md`, `.ai-factory/ROADMAP.md`, `.ai-factory/RULES.md`, and `.ai-factory/DESCRIPTION.md` as read-only context in this command
 - 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. Ask for confirmation

package/skills/aif-dockerize/SKILL.md

@@ -38,6 +38,27 @@ Read .ai-factory/DESCRIPTION.md
 
 Store project context for later steps. If absent, Step 2 detects everything.
 
+**Read `.ai-factory/skill-context/aif-dockerize/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including Dockerfile,
+  compose files, .dockerignore, and deploy scripts. Templates in this skill are **base structures**.
+  If a skill-context rule says "Dockerfile MUST include X" or "compose MUST have service Y" —
+  you MUST augment the templates accordingly. Generating Docker config that violates skill-context
+  rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ---
 
 ## Step 1: Detect Existing Docker Files & Determine Mode

package/skills/aif-docs/SKILL.md

@@ -38,6 +38,27 @@ Generate, maintain, and improve project documentation following a landing-page R
 - Look for existing docs, comments, API endpoints, CLI commands
 - Check for existing README.md and docs/ directory
 
+**Read `.ai-factory/skill-context/aif-docs/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including README.md,
+  documentation pages, and their templates. The templates in this SKILL.md are **base structures**.
+  If a skill-context rule says "docs MUST include X" or "README MUST have section Y" — you MUST
+  augment the templates accordingly. Generating documentation that violates skill-context rules
+  is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 **Scan for scattered markdown files in project root:**
 
 Use `Glob` to find all `*.md` files in the project root (exclude `node_modules/`, `.ai-factory/`, agent dirs):
@@ -496,3 +517,4 @@ Options:
 4. **Use the project's language** — if project README is in Russian, write docs in Russian
 5. **Preserve existing badges/logos** — don't remove them during restructuring
 6. **Add to .gitignore** if generating HTML: add `docs-html/` to .gitignore
+7. **Ownership boundary** — this command owns documentation artifacts (`README.md`, `docs/*`, and the Documentation section in `AGENTS.md`), not `.ai-factory/ROADMAP.md`, `.ai-factory/RULES.md`, or `.ai-factory/RESEARCH.md`