ai-factory 2.4.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
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-factory",
-  "version": "2.4.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

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
 ---
 

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

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

package/skills/aif-commit/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-commit
 description: Create conventional commit messages by analyzing staged changes. Generates semantic commit messages following the Conventional Commits specification. Use when user says "commit", "save changes", or "create commit".
 argument-hint: "[scope or context]"
-allowed-tools: Read Bash(git *) AskUserQuestion Questions
+allowed-tools: Read Bash(git *) Questions
 disable-model-invocation: false
 ---
 

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

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

package/skills/aif-evolve/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-evolve
 description: Self-improve AI Factory skills based on project context, accumulated patches, and codebase patterns. Analyzes what went wrong, what works, and enhances skills to prevent future issues. Use when you want to make AI smarter for your project.
 argument-hint: '[skill-name or "all"]'
-allowed-tools: Read Write Edit Glob Grep Bash(git *) AskUserQuestion Questions
+allowed-tools: Read Write Edit Glob Grep Bash(git *) Questions
 disable-model-invocation: true
 ---
 

package/skills/aif-explore/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-explore
 description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
 argument-hint: "[topic or plan name]"
-allowed-tools: Read Glob Grep Write Edit Bash AskUserQuestion Questions
+allowed-tools: Read Glob Grep Write Edit Bash Questions
 disable-model-invocation: true
 ---
 

package/skills/aif-fix/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-fix
 description: Fix a specific bug or problem in the codebase. Supports two modes - immediate fix or plan-first. Without arguments executes existing FIX_PLAN.md. Always suggests test coverage and adds logging. Use when user says "fix bug", "debug this", "something is broken", or pastes an error message.
 argument-hint: <bug description or error message>
-allowed-tools: Read Write Edit Glob Grep Bash AskUserQuestion Questions Task
+allowed-tools: Read Write Edit Glob Grep Bash Questions Task
 disable-model-invocation: false
 ---
 

package/skills/aif-grounded/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-grounded
 description: Reliability gate for answers. Forces evidence-based reasoning, explicit uncertainty, and “insufficient information” instead of guesses. Use when user says “be 100% sure”, “no hallucinations”, “only if verified”, “grounded answer”, or when stakes are high.
 argument-hint: "[question or task]"
-allowed-tools: Read Write Edit Glob Grep Bash AskUserQuestion Questions
+allowed-tools: Read Write Edit Glob Grep Bash Questions
 disable-model-invocation: true
 ---
 

package/skills/aif-implement/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: aif-implement
 description: Execute implementation tasks from the current plan. Works through tasks sequentially, marks completion, and preserves progress for continuation across sessions. Use when user says "implement", "start coding", "execute plan", or "continue implementation".
-argument-hint: '[task-id or "status"]'
-allowed-tools: Read Write Edit Glob Grep Bash TaskList TaskGet TaskUpdate AskUserQuestion Questions
+argument-hint: '[--list] [@plan-file] [task-id or "status"]'
+allowed-tools: Read Write Edit Glob Grep Bash TaskList TaskGet TaskUpdate Questions
 disable-model-invocation: false
 ---
 
@@ -17,11 +17,39 @@ Execute tasks from the plan, track progress, and enable session continuation.
 **FIRST:** Determine what state we're in:
 
 ```
-1. Check for uncommitted changes (git status)
-2. Check for plan files (.ai-factory/PLAN.md or branch-named)
+1. Parse arguments:
+   - --list → list available plans only (no implementation; STOP)
+   - @<path> → explicit plan file override (highest priority)
+   - <number> → start from specific task
+   - status → status-only mode
+2. Check for uncommitted changes (git status)
 3. Check current branch
 ```
 
+### Step 0.list: List Available Plans (`--list`)
+
+If `$ARGUMENTS` contains `--list`, run read-only plan discovery and stop.
+
+```
+1. Get current branch:
+   git branch --show-current
+2. Convert branch to filename: replace "/" with "-", add ".md"
+3. Check existence of:
+   - .ai-factory/plans/<branch-name>.md
+   - .ai-factory/PLAN.md
+   - .ai-factory/FIX_PLAN.md
+4. Print plan availability summary and usage hints
+5. STOP.
+```
+
+**Important:** In `--list` mode:
+- Do not execute tasks
+- Do not modify files
+- Do not update TaskList statuses
+
+For detailed output format and examples, see:
+- `skills/aif-implement/references/IMPLEMENTATION-GUIDE.md` → "List Available Plans (`--list`)"
+
 ### Step 0.0: Resume / Recovery (after a break or after /clear)
 
 If the user is resuming **the next day**, says the session was **abandoned**, or you suspect context was lost (e.g. after `/clear`), rebuild local context from the repo **before** continuing tasks:
@@ -35,7 +63,7 @@ If the user is resuming **the next day**, says the session was **abandoned**, or
 ```
 
 Then reconcile plan/task state:
-- Ensure the current plan file matches the current branch (PLAN.md takes priority; otherwise branch-named plan).
+- Ensure the current plan file matches the current branch (`@plan-file` override wins; otherwise branch-named plan takes priority over `PLAN.md`).
 - Compare `TaskList` statuses vs plan checkboxes.
   - If code changes for a task appear already implemented but the task is not marked completed, verify quickly and then `TaskUpdate(..., status: "completed")` and update the plan checkbox.
   - If a task is marked completed but the corresponding code is missing (rebase/reset happened), mark it back to pending and discuss with the user.
@@ -137,26 +165,51 @@ If any rule is violated — fix the output before presenting it to the user.
 
 ### Step 0.1: Find Plan File
 
+**If `$ARGUMENTS` contains `@<path>`:**
+
+Use this explicit plan file and skip automatic plan discovery.
+
+```
+1. Extract path after "@"
+2. Resolve relative to project root (absolute paths are also valid)
+3. If file does not exist:
+   "Plan file not found: <path>
+    Provide an existing markdown plan file, for example:
+    - /aif-implement @.ai-factory/PLAN.md
+    - /aif-implement @.ai-factory/plans/feature-user-auth.md"
+   → STOP
+4. If file is .ai-factory/FIX_PLAN.md:
+   → invoke /aif-fix (ownership + cleanup workflow) and STOP
+5. Otherwise use this file as the active plan
+```
+
+Then continue with normal execution using the selected plan file.
+
+**If no `@<path>` override is provided, check plan files in this order:**
+
 **Check for plan files in this order:**
 
 ```
-1. .ai-factory/PLAN.md exists? → Use it (from /aif-plan fast)
-2. No .ai-factory/PLAN.md → Check current git branch:
+1. Check current git branch:
    git branch --show-current
-   → Look for .ai-factory/plans/<branch-name>.md (e.g., .ai-factory/plans/feature-user-auth.md)
-3. No plan files at all → Check .ai-factory/FIX_PLAN.md
+   → Convert branch name to filename: replace "/" with "-", add ".md"
+   → Look for .ai-factory/plans/<branch-name>.md (e.g., feature/user-auth → .ai-factory/plans/feature-user-auth.md)
+2. No branch-based plan → Check .ai-factory/PLAN.md
+3. No branch-based plan and no .ai-factory/PLAN.md → Check .ai-factory/FIX_PLAN.md
    → If exists: invoke /aif-fix (handles its own workflow with patches) and STOP
 ```
 
 **Priority:**
-1. `.ai-factory/PLAN.md` - always takes priority (from `/aif-plan fast`)
-2. Branch-named file - if no .ai-factory/PLAN.md (from `/aif-plan full`)
-3. `.ai-factory/FIX_PLAN.md` - redirect to `/aif-fix` (from `/aif-fix` plan mode)
+1. `@<path>` argument - explicit user-selected plan file
+2. Branch-named file (from `/aif-plan full`) - if it matches current branch
+3. `.ai-factory/PLAN.md` (from `/aif-plan fast`) - fallback when no branch-based plan exists
+4. `.ai-factory/FIX_PLAN.md` - redirect to `/aif-fix` (from `/aif-fix` plan mode)
 
 **Read the plan file** to understand:
 - Context and settings (testing, logging preferences)
 - Commit checkpoints (when to commit)
 - Task dependencies
+- Task checklist format (`- [ ]` / `- [x]`) to keep progress synced
 
 ### Step 1: Load Current State
 
@@ -311,6 +364,7 @@ Files modified:
 - src/services/search.ts (created)
 - src/api/products/search.ts (created)
 - src/types/search.ts (created)
+Documentation: updated existing docs | created docs/<feature-slug>.md | skipped by user | warn-only (Docs: no/unset)
 
 What's next?
 
@@ -386,17 +440,35 @@ Options:
 If user chooses "Verify first" → suggest invoking `/aif-verify`.
 If user chooses "Skip to commit" → suggest invoking `/aif-commit`.
 
-**Check if documentation needs updating:**
-
-Read the plan file settings. If documentation preference is set to "yes" (from `/aif-plan full` questions), run `/aif-docs` to update documentation.
+**Documentation policy checkpoint (after completion, before plan cleanup):**
 
-If documentation preference is "no" or not set — skip this step silently.
+Read the plan file setting `Docs: yes/no`.
 
-If documentation preference is "yes":
+If plan setting is `Docs: yes`:
 ```
-📝 Updating project documentation...
+AskUserQuestion: Documentation checkpoint — how should we document this feature?
+
+Options:
+1. Update existing docs (recommended) — invoke /aif-docs
+2. Create a new feature doc page — invoke /aif-docs with feature-page context
+3. Skip documentation
 ```
-→ Invoke `/aif-docs` to analyze changes and update docs.
+
+Handling:
+- Option 1 → invoke `/aif-docs` to update README/docs based on completed work
+- Option 2 → invoke `/aif-docs` with context to create `docs/<feature-slug>.md`, include sections (Summary, Usage/user-facing behavior, Configuration, API/CLI changes, Examples, Troubleshooting, See Also), and add a README docs-table link
+- Option 3 → do not invoke `/aif-docs`; emit `WARN [docs] Documentation skipped by user`
+
+If plan setting is `Docs: no` or setting is unset:
+- Do **not** show a mandatory docs checkpoint prompt
+- Do **not** invoke `/aif-docs` automatically
+- Emit `WARN [docs] Docs policy is no/unset; skipping documentation checkpoint`
+
+**Always include documentation outcome in the final completion output:**
+- `Documentation: updated existing docs`
+- `Documentation: created docs/<feature-slug>.md`
+- `Documentation: skipped by user`
+- `Documentation: warn-only (Docs: no/unset)`
 
 **Handle plan file after completion:**
 
@@ -498,6 +570,19 @@ To merge and clean up later:
 ```
 Continues from next incomplete task.
 
+### List Available Plans
+```
+/aif-implement --list
+```
+Lists `.ai-factory/PLAN.md`, `.ai-factory/FIX_PLAN.md`, and current-branch `.ai-factory/plans/<branch>.md` (if present), then exits without implementation.
+
+### Use Explicit Plan File
+```
+/aif-implement @my-custom-plan.md
+/aif-implement @.ai-factory/plans/feature-user-auth.md status
+```
+Uses the provided plan file instead of auto-detecting by branch/default files.
+
 ### Start from Specific Task
 ```
 /aif-implement 5

package/skills/aif-implement/references/IMPLEMENTATION-GUIDE.md

@@ -38,6 +38,56 @@ What would you like to do?
 
 Tasks are persisted in the conversation/project state.
 
+## List Available Plans (`--list`)
+
+When the user runs:
+
+```
+/aif-implement --list
+```
+
+Use read-only discovery and stop without executing any tasks.
+
+### Discovery steps
+
+```
+git branch --show-current
+```
+
+Then derive:
+- `branchPlan = .ai-factory/plans/<branch-with-slashes-replaced-by-hyphens>.md`
+- `fastPlan = .ai-factory/PLAN.md`
+- `fixPlan = .ai-factory/FIX_PLAN.md`
+
+Check which files exist and print:
+
+```
+## Available Plans
+Current branch: <branch>
+- [x| ] <branchPlan>   (current-branch plan)
+- [x| ] <fastPlan>     (fast plan)
+- [x| ] <fixPlan>      (fix plan)
+
+Use:
+- /aif-implement @<path>  to execute a specific plan
+- /aif-implement          to use automatic priority
+```
+
+If no plans exist, print:
+
+```
+No plan files found. Create one with:
+- /aif-plan full <description>
+- /aif-plan fast <description>
+- /aif-fix <bug description>
+```
+
+### Constraints
+
+- Do not execute implementation tasks
+- Do not modify files
+- Do not call `TaskUpdate`
+
 ### Recovery after a break or after /clear
 
 If the user is resuming later and you don't have prior conversational context, rebuild context from git + the plan file before continuing:
@@ -50,7 +100,7 @@ git diff --stat
 ```
 
 Then:
-- Re-open the active plan file and confirm it matches the current branch.
+- Re-open the active plan file (`@plan-file` override if provided; otherwise branch plan first, then `PLAN.md`, then `FIX_PLAN.md` redirect to `/aif-fix`).
 - Use `TaskList` to find `in_progress` first, otherwise the next pending task.
 - If `TaskList` and plan checkboxes disagree, reconcile (verify code, then update `TaskUpdate` + plan checkbox).
 

package/skills/aif-improve/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: aif-improve
-description: Refine and enhance an existing implementation plan with a second iteration. Re-analyzes the codebase, checks for gaps, missing tasks, wrong dependencies, and improves the plan quality. Use after /aif-plan to polish the plan before implementation.
-argument-hint: "[improvement prompt or empty for auto-review]"
-allowed-tools: Read Write Edit Glob Grep Bash(git *) TaskCreate TaskUpdate TaskList TaskGet AskUserQuestion Questions
+description: Refine and enhance an existing implementation plan with a second iteration. Re-analyzes the codebase, checks for gaps, missing tasks, wrong dependencies, and improves the plan quality. Use after /aif-plan to polish the plan before implementation, or to improve an existing /aif-fix plan.
+argument-hint: "[--list] [@plan-file] [improvement prompt or empty for auto-review]"
+allowed-tools: Read Write Edit Glob Grep Bash(git *) TaskCreate TaskUpdate TaskList TaskGet Questions
 disable-model-invocation: false
 ---
 
@@ -24,18 +24,57 @@ enhanced plan with better tasks, correct dependencies, more detail
 
 ### Step 0: Find the Plan
 
+**First parse arguments:**
+
+```
+- --list    → list available plans only (read-only, then STOP)
+- @<path>   → explicit plan file override (highest priority)
+- remaining argument text → optional improvement prompt
+```
+
+When both are present, `--list` wins and no refinement is executed.
+
+### Step 0.list: List Available Plans (`--list`)
+
+If `$ARGUMENTS` contains `--list`, run read-only discovery and stop.
+
+```
+1. Get current branch:
+   git branch --show-current
+2. Convert branch to filename: replace "/" with "-", add ".md"
+3. Check existence of:
+   - .ai-factory/plans/<branch-name>.md
+   - .ai-factory/PLAN.md
+   - .ai-factory/FIX_PLAN.md
+4. Print availability summary and usage hints:
+   - /aif-improve @<path> <optional prompt>
+   - /aif-improve <optional prompt>      # automatic priority
+5. If none found, suggest creating a plan via /aif-plan or /aif-fix
+6. STOP.
+```
+
+**Important:** In `--list` mode:
+- Do not execute refinement
+- Do not modify files
+- Do not update TaskList/plan content
+
 **Locate the active plan file using this priority:**
 
 ```
-1. .ai-factory/PLAN.md exists? → Use it (from /aif-plan fast)
-2. No .ai-factory/PLAN.md → Check current git branch:
+1. If `$ARGUMENTS` contains `@<path>`:
+   - Resolve the path (relative to project root; absolute paths allowed)
+   - If file exists → use it
+   - If missing → show "Plan file not found: <path>" and STOP
+2. No explicit `@<path>` override → Check current git branch:
    git branch --show-current
    → Convert branch name to filename: replace "/" with "-", add ".md"
-   → Look for .ai-factory/plans/<branch-name>.md
+   → Look for .ai-factory/plans/<branch-name>.md (from /aif-plan full)
    Example: feature/user-auth → .ai-factory/plans/feature-user-auth.md
+3. No branch-based plan → Check .ai-factory/PLAN.md (from /aif-plan fast)
+4. No branch-based plan and no .ai-factory/PLAN.md → Check .ai-factory/FIX_PLAN.md (from /aif-fix plan mode)
 ```
 
-**If NO plan file found at either location:**
+**If NO plan file found at any location:**
 
 ```
 No active plan found.
@@ -43,6 +82,7 @@ No active plan found.
 To create a plan first, use:
 - /aif-plan full <description>  — for a new feature (creates branch + plan)
 - /aif-plan fast <description>  — for a quick task plan
+- /aif-fix <bug description>    — for a bugfix plan (.ai-factory/FIX_PLAN.md)
 ```
 
 → **STOP here.** Do not proceed without a plan file.
@@ -175,7 +215,7 @@ Compare the plan against what you found. Categorize issues:
 
 **3.6: User-prompted improvements (if $ARGUMENTS provided)**
 
-If the user provided specific improvement instructions in `$ARGUMENTS`:
+If the user provided specific improvement instructions in `$ARGUMENTS` (excluding `--list` and `@<path>` tokens):
 - Apply the user's feedback to the plan
 - Look for tasks that need modification based on the prompt
 - Add new tasks if the user's prompt requires them
@@ -377,16 +417,47 @@ Apply? → Yes → Changes applied
 ```
 User: /aif-improve
 
+→ Branch: main
+→ No .ai-factory/plans/main.md found
 → No .ai-factory/PLAN.md found
-→ Branch: main (no feature branch)
+→ No .ai-factory/FIX_PLAN.md found
 → No plan file found
 
 "No active plan found. Create one first:
 - /aif-plan full <description>
-- /aif-plan fast <description>"
+- /aif-plan fast <description>
+- /aif-fix <bug description>"
+```
+
+### Example 4: Explicit plan file
+
+```
+User: /aif-improve @my-custom-plan.md add rollback and edge-case handling
+
+→ Explicit plan override: my-custom-plan.md
+→ Found plan: my-custom-plan.md
+→ User wants: rollback + edge-case handling
+→ Deep codebase analysis...
+→ Report prepared
+```
+
+### Example 5: List mode
+
+```
+User: /aif-improve --list
+
+## Available Plans
+Current branch: feature/user-auth
+- [x] .ai-factory/plans/feature-user-auth.md
+- [ ] .ai-factory/PLAN.md
+- [x] .ai-factory/FIX_PLAN.md
+
+Use:
+- /aif-improve @.ai-factory/plans/feature-user-auth.md
+- /aif-improve add validation and retries
 ```
 
-### Example 4: Plan already looks good
+### Example 6: Plan already looks good
 
 ```
 User: /aif-improve

package/skills/aif-loop/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-loop
 description: Run a strict multi-iteration Reflex Loop with phases (PLAN, PRODUCE||PREPARE, EVALUATE, CRITIQUE, REFINE) to improve an artifact until quality gates pass or iteration limits are reached. Use when user asks for iterative refinement, quality-gated generation, or "generate -> critique -> refine" loops.
 argument-hint: "[new|resume|status|stop|list|history|clean] [task or alias]"
-allowed-tools: Read Write Edit Glob Grep Bash Task AskUserQuestion Questions
+allowed-tools: Read Write Edit Glob Grep Bash Task Questions
 disable-model-invocation: true
 ---
 

package/skills/aif-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-plan
 description: Plan implementation for a feature or task. Two modes — fast (no branch) or full (git branch + plan). Use when user says "plan", "new feature", "start feature", "create tasks".
 argument-hint: "[fast | full] [--parallel | --list | --cleanup <branch>] <description>"
-allowed-tools: Read Write Glob Grep Bash(git *) Bash(cd *) Bash(cp *) Bash(mkdir *) Bash(basename *) TaskCreate TaskUpdate TaskList AskUserQuestion Questions Task
+allowed-tools: Read Write Glob Grep Bash(git *) Bash(cd *) Bash(cp *) Bash(mkdir *) Bash(basename *) TaskCreate TaskUpdate TaskList Questions Task
 disable-model-invocation: false
 ---
 
@@ -174,9 +174,9 @@ AskUserQuestion: Before we start, a few questions:
    - [ ] Standard - INFO level, key events only
    - [ ] Minimal - only WARN/ERROR
 
-3. Update documentation after implementation?
-   - [ ] Yes, update docs (/aif-docs)
-   - [ ] No, skip docs
+3. Documentation policy after implementation?
+   - [ ] Yes — mandatory docs checkpoint at completion (recommended)
+   - [ ] No — warn-only (`WARN [docs]`), no mandatory checkpoint
 
 4. Roadmap milestone linkage (only if `.ai-factory/ROADMAP.md` exists):
    - [ ] Link this plan to a milestone
@@ -192,6 +192,10 @@ AskUserQuestion: Before we start, a few questions:
 
 Store all preferences — they will be used in the plan file and passed to `/aif-implement`.
 
+Docs policy semantics:
+- `Docs: yes` → `/aif-implement` MUST show a mandatory documentation checkpoint and route docs changes through `/aif-docs`
+- `Docs: no` (or unset) → `/aif-implement` emits `WARN [docs]` and continues without a mandatory docs checkpoint
+
 **If `.ai-factory/ROADMAP.md` exists and the user chose milestone linkage:**
 - Read `.ai-factory/ROADMAP.md` and list candidate milestones (prefer unchecked items)
 - Ask the user to pick one milestone (or type a custom one)
@@ -414,7 +418,7 @@ CONTEXT FROM /aif-plan:
 - Plan file: .ai-factory/plans/<branch-name>.md
 - Testing: yes/no
 - Logging: verbose/standard/minimal
-- Docs: yes/no
+- Docs: yes/no  # yes => mandatory docs checkpoint, no => warn-only
 ```
 
 **Full mode normal:** STOP after planning. The user reviews the plan and decides when to implement.

package/skills/aif-plan/references/TASK-FORMAT.md

@@ -11,7 +11,7 @@ Created: [date]
 ## Settings
 - Testing: yes/no
 - Logging: verbose/standard/minimal
-- Docs: yes/no
+- Docs: yes/no  # yes => mandatory docs checkpoint in /aif-implement, no/unset => WARN [docs] only
 
 ## Roadmap Linkage (optional)
 <!-- Only when .ai-factory/ROADMAP.md exists -->

package/skills/aif-roadmap/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-roadmap
 description: Create or update a project roadmap with major milestones. Generates .ai-factory/ROADMAP.md — a strategic checklist of high-level goals. Use when user says "roadmap", "project plan", "milestones", or "what to build next".
 argument-hint: "[check | project vision or requirements]"
-allowed-tools: Read Write Edit Glob Grep Bash(git *) AskUserQuestion Questions
+allowed-tools: Read Write Edit Glob Grep Bash(git *) Questions
 disable-model-invocation: true
 ---
 

package/skills/aif-rules/SKILL.md

@@ -2,7 +2,7 @@
 name: aif-rules
 description: Add project-specific rules and conventions to .ai-factory/RULES.md. Each invocation appends new rules. These rules are automatically loaded by /aif-implement before execution. Use when user says "add rule", "remember this", "convention", or "always do X".
 argument-hint: "[rule text or topic]"
-allowed-tools: Read Write Edit Glob Grep AskUserQuestion Questions
+allowed-tools: Read Write Edit Glob Grep Questions
 disable-model-invocation: true
 ---
 

package/skills/aif-verify/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   nothing was forgotten, code compiles, tests pass, and quality standards are met.
   Use after "/aif-implement" completes, or when user says "verify", "check work", "did we miss anything".
 argument-hint: "[--strict]"
-allowed-tools: Read Edit Glob Grep Bash(git *) Bash(npm *) Bash(npx *) Bash(yarn *) Bash(pnpm *) Bash(bun *) Bash(go *) Bash(python *) Bash(php *) Bash(composer *) Bash(cargo *) Bash(make *) Bash(task *) Bash(just *) Bash(mage *) TaskList TaskGet AskUserQuestion Questions
+allowed-tools: Read Edit Glob Grep Bash(git *) Bash(npm *) Bash(npx *) Bash(yarn *) Bash(pnpm *) Bash(bun *) Bash(go *) Bash(python *) Bash(php *) Bash(composer *) Bash(cargo *) Bash(make *) Bash(task *) Bash(just *) Bash(mage *) TaskList TaskGet Questions
 disable-model-invocation: false
 metadata:
   author: AI Factory