ai-factory 2.3.0 → 2.5.0

package/README.md

@@ -131,7 +131,7 @@ AI Factory can generate and maintain your project docs with a single command:
 
 - **Generates docs from scratch** — analyzes your codebase and creates a lean README + detailed `docs/` pages by topic
 - **Cleans up scattered files** — finds loose CONTRIBUTING.md, ARCHITECTURE.md, SETUP.md in your root and consolidates them into a structured `docs/` directory
-- **Keeps docs in sync** — integrates with `/aif-implement` so documentation is updated automatically after each feature
+- **Keeps docs in sync** — integrates with `/aif-implement` docs policy (`Docs: yes` = mandatory docs checkpoint routed to `/aif-docs`, `Docs: no` = visible `WARN [docs]`)
 - **Builds a docs website** — `--web` generates a static HTML site with navigation and dark mode, ready to host
 
 ---
@@ -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.5.0",
   "type": "module",
   "description": "CLI tool for automating AI agent context setup in projects",
   "main": "dist/cli/index.js",

package/skills/aif/SKILL.md

@@ -2,7 +2,7 @@
 name: aif
 description: Set up agent context for a project. Analyzes tech stack, installs relevant skills from skills.sh, generates custom skills, and configures MCP servers. Use when starting new project, setting up AI context, or asking "set up project", "configure AI", "what skills do I need".
 argument-hint: "[project description]"
-allowed-tools: Read Glob Grep Write Bash(mkdir *) Bash(npx skills *) Bash(python *security-scan*) Bash(rm -rf *) Skill WebFetch AskUserQuestion Questions
+allowed-tools: Read Glob Grep Write Bash(mkdir *) Bash(npx skills *) Bash(python *security-scan*) Bash(rm -rf *) Skill WebFetch Questions
 ---
 
 # AI Factory - Project Setup
@@ -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

@@ -2,7 +2,7 @@
 name: aif-architecture
 description: Generate architecture guidelines for the project. Analyzes tech stack from DESCRIPTION.md, recommends an architecture pattern, and creates .ai-factory/ARCHITECTURE.md. Use when setting up project architecture, asking "which architecture", or after /aif setup.
 argument-hint: "[clean|ddd|microservices|monolith|layers]"
-allowed-tools: Read Write Glob Grep Bash(mkdir *) AskUserQuestion Questions
+allowed-tools: Read Write Glob Grep Bash(mkdir *) Questions
 disable-model-invocation: false
 ---
 
@@ -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

@@ -5,7 +5,7 @@ description: >-
   If a build file already exists, improves it by adding missing targets and best practices.
   Use when user says "generate makefile", "create taskfile", "add justfile", "setup mage", or "build automation".
 argument-hint: "[makefile|taskfile|justfile|mage]"
-allowed-tools: Read Edit Glob Grep Write Bash(git *) AskUserQuestion Questions
+allowed-tools: Read Edit Glob Grep Write Bash(git *) Questions
 disable-model-invocation: false
 metadata:
   author: AI Factory
@@ -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

@@ -2,7 +2,7 @@
 name: aif-ci
 description: Generate CI/CD pipeline (GitHub Actions / GitLab CI) with linting, static analysis, tests, security. Use when user says "ci", "setup ci", "github actions", "gitlab ci", "pipeline".
 argument-hint: "[github|gitlab] [--enhance]"
-allowed-tools: Read Edit Glob Grep Write Bash(git *) AskUserQuestion Questions
+allowed-tools: Read Edit Glob Grep Write Bash(git *) Questions
 disable-model-invocation: true
 metadata:
   author: AI Factory
@@ -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 *) 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

@@ -6,7 +6,7 @@ description: >-
   Includes production security audit. Use when user says "dockerize", "add docker", "docker compose",
   "containerize", or "setup docker".
 argument-hint: "[--audit]"
-allowed-tools: Read Edit Glob Grep Write Bash(git *) Bash(docker *) AskUserQuestion Questions WebSearch WebFetch
+allowed-tools: Read Edit Glob Grep Write Bash(git *) Bash(docker *) Questions WebSearch WebFetch
 disable-model-invocation: false
 metadata:
   author: AI Factory
@@ -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

@@ -2,7 +2,7 @@
 name: aif-docs
 description: Generate and maintain project documentation. Creates a lean README as a landing page with detailed docs/ directory split by topic. Use when user says "create docs", "write documentation", "update docs", "generate readme", or "document project".
 argument-hint: "[--web]"
-allowed-tools: Read Write Edit Glob Grep Bash(mkdir, npx, python) AskUserQuestion Questions WebFetch WebSearch
+allowed-tools: Read Write Edit Glob Grep Bash(mkdir, npx, python) Questions WebFetch WebSearch
 disable-model-invocation: false
 metadata:
   author: AI Factory
@@ -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`