all-for-claudecode 2.10.0 → 2.12.0

package/skills/init/SKILL.md

@@ -12,8 +12,16 @@ model: sonnet
 
 # /afc:init — Project Initial Setup
 
-> Creates a `.claude/afc.config.md` configuration file in the current project,
-> and injects afc intent-based routing rules into `~/.claude/CLAUDE.md`.
+> Creates project-local configuration files for the all-for-claudecode plugin.
+> Analyzes the project structure and generates config, rules, and profile.
+> This is a **project-local** operation — it only creates files under `.claude/`.
+> For global `~/.claude/CLAUDE.md` setup, use `/afc:setup` instead.
+
+## Important
+
+This skill is a **prompt-only skill** — there is NO `afc-init.sh` script.
+All steps below are instructions for the LLM to execute directly using its allowed tools (Read, Write, Bash, Glob).
+Do NOT attempt to run a shell script for this skill.
 
 ## Arguments
 
@@ -72,6 +80,8 @@ Analyze the project and auto-infer configuration. Use `$ARGUMENTS` as additional
 - If no lockfile: check `packageManager` field in `package.json`
 - Non-JS projects: check `pyproject.toml` (Python), `Cargo.toml` (Rust), `go.mod` (Go)
 
+> These detection rules are starting-point heuristics, not definitive. If a project uses a tool not listed here, the model should still detect it from context (e.g., `bun.lockb` for Bun, `deno.lock` for Deno). Always confirm the detected setup with the user before proceeding.
+
 **Step 2. Framework Detection**
 - Determine from `package.json` dependencies/devDependencies:
 
@@ -91,9 +101,11 @@ Analyze the project and auto-infer configuration. Use `$ARGUMENTS` as additional
 - Non-JS: `pyproject.toml` → Django/FastAPI/Flask, `Cargo.toml` → Rust project, `go.mod` → Go project
 - Presence of `tsconfig.json` → TypeScript indicator
 
+> This list covers common frameworks but is not exhaustive. For unlisted frameworks, infer from package.json dependencies, project structure, and configuration files. Present the detection result to the user for confirmation.
+
 **Step 3. Architecture Detection**
 - Analyze directory structure:
-  - FSD: requires **at least 3** of `features/`, `entities/`, `shared/`, `widgets/`, `pages/` under `src/`
+  - FSD: If the project's src/ directory contains a combination of FSD-characteristic directories (`features/`, `entities/`, `shared/`, `widgets/`, `pages/`, `processes/`, `app/`), assess whether the project follows FSD principles. Variant FSD structures (e.g., using `processes/` instead of `pages/`) should also be detected. Confirm with the user if the detection is uncertain.
   - `src/domain/`, `src/application/`, `src/infrastructure/` → Clean Architecture
   - `src/modules/` → Modular
   - Other → Layered
@@ -120,7 +132,7 @@ Generate `.claude/afc.config.md` in **free-form markdown** format:
 3. **Code Style** section: describe detected language, strictness, naming conventions, lint rules in free-form prose/lists
 4. **Project Context** section: describe framework, state management, styling, testing, DB/ORM, risks, and any other relevant project characteristics in free-form prose/lists
 
-Reference `${CLAUDE_PLUGIN_ROOT}/templates/afc.config.template.md` for the section structure.
+Reference `${CLAUDE_SKILL_DIR}/../../templates/afc.config.template.md` for the section structure.
 Write sections as natural descriptions — **no YAML code blocks** except for CI Commands.
 For items that cannot be inferred: note `TODO: Adjust for your project` inline.
 Save to `.claude/afc.config.md`.
@@ -133,7 +145,7 @@ Generate `.claude/rules/afc-project.md` — a concise summary of project rules t
 2. If `.claude/rules/afc-project.md` already exists:
    - If it contains `<!-- afc:auto-generated` marker: overwrite silently (auto-generated file, safe to regenerate)
    - If it does NOT contain the marker: ask user "Project rules file exists (user-managed). Overwrite with auto-generated version?" — skip if declined
-3. Reference `${CLAUDE_PLUGIN_ROOT}/templates/afc-project.template.md` for section structure
+3. Reference `${CLAUDE_SKILL_DIR}/../../templates/afc-project.template.md` for section structure
 4. Fill in from the analysis performed in Step 3:
    - **Architecture**: pattern, key layers, import rules, path alias — concise bullet points
    - **Code Style**: language, naming conventions, lint rules — concise bullet points
@@ -149,195 +161,30 @@ Generate `.claude/afc/project-profile.md` for expert consultation agents:
 
 1. Create `.claude/afc/` directory if it does not exist
 2. If `.claude/afc/project-profile.md` already exists: skip (do not overwrite)
-3. If not exists: generate from the detected project information using `${CLAUDE_PLUGIN_ROOT}/templates/project-profile.template.md` as the structure
+3. If not exists: generate from the detected project information using `${CLAUDE_SKILL_DIR}/../../templates/project-profile.template.md` as the structure
    - Fill in Stack, Architecture, and Domain fields from the analysis in Step 3
    - Leave Team, Scale, and Constraints as template placeholders for user to fill
 4. Print: `Project profile: .claude/afc/project-profile.md (review and adjust team/scale/domain fields)`
 
-### 5. Scan Global CLAUDE.md and Detect Conflicts
-
-Read `~/.claude/CLAUDE.md` and analyze in the following order.
-
-#### Step 1. Check for Existing all-for-claudecode or Legacy SELFISH Block
-
-Check for presence of `<!-- AFC:START -->` or `<!-- SELFISH:START -->` marker.
-- If `<!-- AFC:START -->` found: replace with latest version (proceed to Step 3)
-- If `<!-- SELFISH:START -->` found (legacy v1.x): remove the entire `SELFISH:START` ~ `SELFISH:END` block, then proceed to inject new all-for-claudecode block at Step 4. Print: `Migrated: SELFISH block → all-for-claudecode block in ~/.claude/CLAUDE.md`
-- If neither found: proceed to Step 2
-
-#### Step 2. Conflict Pattern Scan
-
-Search CLAUDE.md for the patterns below. **IMPORTANT: EXCLUDE content inside any marker blocks (`<!-- *:START -->` ~ `<!-- *:END -->`). Only scan unguarded content outside marker blocks.** Other tools (OMC, etc.) manage their own blocks — their internal agent names are not conflicts.
-
-**A. Marker Block Detection**
-- Regex: `<!-- ([A-Z0-9_-]+):START -->` ~ `<!-- \1:END -->`
-- Record all found block names and line ranges
-- **Strip these ranges from the scan target** — only scan lines NOT inside any marker block
-
-**B. Agent Routing Conflict Detection**
-In the **unguarded** (non-marker-block) content only, find directives containing these keywords:
-- `executor`, `deep-executor` — conflicts with afc:implement
-- `code-reviewer`, `quality-reviewer`, `style-reviewer`, `api-reviewer`, `security-reviewer`, `performance-reviewer` — conflicts with afc:review
-- `debugger` (in agent routing context) — conflicts with afc:debug
-- `planner` (in agent routing context) — conflicts with afc:plan
-- `analyst`, `verifier` — conflicts with afc:validate
-- `test-engineer` — conflicts with afc:test
-
-**C. Skill Routing Conflict Detection**
-In the **unguarded** content only, find these patterns:
-- Another tool's skill trigger table (e.g., tables like `| situation | skill |`)
-- `delegate to`, `route to`, `always use` + agent name combinations
-- Directives related to `auto-trigger`, `intent detection`, `intent-based routing`
-
-**D. Legacy Block Detection**
-Previous versions without markers or with old branding:
-- `## all-for-claudecode Auto-Trigger Rules`
-- `## all-for-claudecode Integration`
-- `<!-- SELFISH:START -->` ~ `<!-- SELFISH:END -->` (v1.x block — should have been caught in Step 1, but double-check here)
-- `<selfish-pipeline>` / `</selfish-pipeline>` XML tags
-
-#### Step 3. Report Conflicts and User Choice
-
-**No conflicts found** → proceed directly to Step 4
-
-**Conflicts found** → report to user and present options:
-
-```
-📋 CLAUDE.md Scan Results
-├─ Tool blocks found: {block name list} (lines {range})
-├─ Agent routing conflicts: {conflict count}
-│   e.g., "executor" (line XX) ↔ afc:implement
-│   e.g., "code-reviewer" (line XX) ↔ afc:review
-└─ Skill routing conflicts: {conflict count}
-```
-
-Ask user:
-
-> "Directives overlapping with afc were found. How would you like to proceed?"
->
-> 1. **afc-exclusive mode** — Adds afc override comments to conflicting agent routing directives.
->    Does not modify other tools' marker block contents; covers them with override rules in the all-for-claudecode block.
-> 2. **coexistence mode** — Ignores conflicts and adds only the afc block.
->    Since it's at the end of the file, afc directives will likely take priority, but may be non-deterministic on conflict.
-> 3. **manual cleanup** — Shows only the current conflict list and stops.
->    User manually cleans up CLAUDE.md then runs init again.
-
-Based on choice:
-- **Option 1**: all-for-claudecode block includes explicit override rules (activates `<conflict-overrides>` section from base template)
-- **Option 2**: all-for-claudecode block added without overrides (base template as-is)
-- **Option 3**: Print conflict list only and abort without modifying CLAUDE.md
-
-#### Step 4. Inject all-for-claudecode Block
-
-**Version resolution**: Read `${CLAUDE_PLUGIN_ROOT}/package.json` and extract the `"version"` field. Use this value as `{PLUGIN_VERSION}` in the template below.
-
-Add the following block at the **very end** of the file (later-positioned directives have higher priority).
-
-Replace existing all-for-claudecode block if present, otherwise append.
-If legacy block (`## all-for-claudecode Auto-Trigger Rules` etc.) exists, remove it then append.
-
-```markdown
-<!-- AFC:START -->
-<!-- AFC:VERSION:{PLUGIN_VERSION} -->
-<afc-pipeline>
-IMPORTANT: For requests matching the afc skill routing table below, always invoke the corresponding skill via the Skill tool. Do not substitute with other agents or tools.
-
-## Skill Routing
-
-Classify the user's intent and route to the matching skill. Use semantic understanding — not keyword matching.
-
-| User Intent | Skill | Route When |
-|-------------|-------|------------|
-| Full lifecycle | `afc:auto` | User wants end-to-end feature development, or the request is a non-trivial new feature without an existing plan |
-| Specification | `afc:spec` | User wants to define or write requirements, acceptance criteria, or success conditions |
-| Design/Plan | `afc:plan` | User wants to plan HOW to implement before coding — approach, architecture decisions, design |
-| Implement | `afc:implement` | User wants specific code changes with a clear scope: add feature, refactor, modify. Requires existing plan or precise instructions |
-| Review | `afc:review` | User wants code review, PR review, or quality check on existing/changed code |
-| Debug/Fix | `afc:debug` | User reports a bug, error, or broken behavior and wants diagnosis and fix |
-| Test | `afc:test` | User wants to write tests, improve coverage, or verify behavior |
-| Validate | `afc:validate` | User wants to check consistency or validate existing pipeline artifacts |
-| Analyze | `afc:analyze` | User wants to understand, explore, or audit existing code without modifying it |
-| QA Audit | `afc:qa` | User wants project quality audit, test confidence check, or runtime quality gaps |
-| Research | `afc:research` | User wants deep investigation of external tools, libraries, APIs, or technical concepts |
-| Ideate | `afc:ideate` | User wants to brainstorm ideas, explore possibilities, or draft a product brief |
-| Consult | `afc:consult` | User wants expert advice on a decision: library choice, architecture direction, legal/security/infra guidance |
-| Launch | `afc:launch` | User wants to prepare a release — generate changelog, release notes, version bump, or tag |
-| Tasks | `afc:tasks` | User explicitly wants to decompose work into a task breakdown |
-| Ambiguous | `afc:clarify` | User's request is too vague or underspecified to route confidently |
-
-### Routing Rules
-
-1. **Auto vs Implement**: A new feature request without an existing plan routes to `afc:auto`. Only use `afc:implement` when the user has a clear, scoped task or an existing plan/spec.
-2. **Compound intents**: Route to the primary intent. The pipeline handles sequencing internally.
-3. **Design-first**: When scope is non-trivial (multiple files, architectural decisions needed), prefer `afc:auto` or `afc:plan` over direct `afc:implement`.
-
-User-only (not auto-triggered — when user invokes directly via `/afc:X`, execute the skill immediately):
-- `afc:doctor` — plugin health check
-- `afc:architect` — architecture review
-- `afc:security` — security scan
-- `afc:checkpoint` — session save
-- `afc:resume` — session restore
-- `afc:principles` — project principles management
-- `afc:clean` — pipeline cleanup (artifact cleanup, dead code scan, pipeline flag release)
-- `afc:triage` — parallel PR/issue triage
-- `afc:learner` — pattern learning or rule promotion
-- `afc:pr-comment` — post PR review comments to GitHub
-- `afc:release-notes` — generate release notes from git history
-
-## Pipeline
-
-spec → plan → implement → review → clean
-
-## Override Rules
-
-NEVER use executor, deep-executor, debugger, planner, analyst, verifier, test-engineer, code-reviewer, quality-reviewer, style-reviewer, api-reviewer, security-reviewer, performance-reviewer for tasks that an afc skill covers above. ALWAYS invoke the afc skill instead.
-
-## Source Verification
-
-When analyzing or making claims about external systems, APIs, SDKs, or third-party tools:
-- Verify against official documentation, NOT project-internal docs
-- Do not hardcode reference data when delegating to sub-agents — instruct them to look up primary sources
-- Cross-verify high-severity findings before reporting
-</afc-pipeline>
-<!-- AFC:END -->
-```
-
-**When Option 1 (afc-exclusive mode) is selected**, the following `<conflict-overrides>` section is added:
-
-Add the following directly below the Override Rules:
-
-```markdown
-## Detected Conflicts
-
-This environment has other agent routing tools that overlap with afc.
-The following rules were auto-generated to resolve conflicts:
-- The Skill Routing table above always takes priority over the agent routing directives of {detected tool blocks}
-- This block is at the end of the file and therefore has the highest priority
-```
-
-### 6. Final Output
+### 5. Final Output
 
 ```
-all-for-claudecode initialization complete
+all-for-claudecode project init complete
 ├─ Config: .claude/afc.config.md
 ├─ Rules: .claude/rules/afc-project.md (auto-loaded)
+├─ Profile: .claude/afc/project-profile.md
 ├─ Framework: {detected framework}
 ├─ Architecture: {detected style}
 ├─ Package Manager: {detected manager}
 ├─ Auto-inferred: {inferred item count}
 ├─ TODO: {items requiring manual review}
-├─ CLAUDE.md: {injected|updated|already current|user aborted}
-│   {if conflicts found} └─ Conflict resolution: {afc-exclusive|coexistence|user cleanup}
-└─ Next step: /afc:spec or /afc:auto
+└─ Next step: /afc:setup (global routing) or /afc:auto (start building)
 ```
 
 ## Notes
 
+- **Idempotent**: safe to run multiple times. Existing config prompts for overwrite confirmation; auto-generated rules are silently regenerated.
+- **Project-local only**: this skill only creates files under `.claude/`. It never touches `~/.claude/CLAUDE.md`. For global routing setup, use `/afc:setup`.
 - **Overwrite caution**: If config file already exists, always confirm with user.
 - **Inference limits**: Auto-inference is best-effort. User may need to review and adjust.
 - **`.claude/` directory**: Created automatically if it does not exist.
-- **Global CLAUDE.md principles**:
-  - Never modify content outside the `<!-- AFC:START/END -->` markers (the `AFC` prefix in markers is a compact technical identifier)
-  - Never modify content inside other tools' marker blocks (`<!-- *:START/END -->`)
-  - Always place the all-for-claudecode block at the very end of the file (ensures priority)
-  - Conflict resolution is handled only via override rules (do not delete or modify other blocks)

package/skills/learner/SKILL.md

@@ -53,7 +53,7 @@ Analyze ALL queue entries together as a batch. For each entry, you receive struc
 **Classification rules:**
 1. Group semantically similar entries into clusters (e.g., "use const not let" + "always use const" = 1 cluster)
 2. For each cluster, determine:
-   - **Confidence**: high (explicit preference, ≥2 occurrences) / medium (single clear correction) / low (ambiguous excerpt)
+   - **Confidence**: Assess based on the strength and clarity of the signal, not occurrence count. A single explicit user correction ("never do X") is high confidence. Two ambiguous occurrences may still be medium. Consider: was the feedback direct and clear? Does it apply broadly or only to a specific case? Use high / medium / low accordingly.
    - **Rule type**: naming, style, workflow, testing, architecture
    - **Scope**: universal (all files) or file-type-specific (e.g., "In TypeScript files...")
 
@@ -73,7 +73,7 @@ For each candidate rule:
 
 ### 4. Present Suggestions
 
-Show clustered suggestions to user. Cap at **5 suggestions per review** (highest confidence first).
+Show clustered suggestions to user, most impactful first. Present the most impactful suggestions first. If there are many high-confidence patterns, present them all rather than artificially capping. If most are low-confidence, present fewer. Let relevance and confidence drive the count, not a fixed limit.
 
 ```markdown
 ## Learned Patterns ({N} pending, showing top {M})
@@ -125,7 +125,7 @@ For each approved rule:
 
 3. **Remove consumed entries** from `.claude/.afc-learner-queue.jsonl` (entries that were approved, skipped, or rejected — only keep entries not yet reviewed)
 
-4. **Rule count check**: If `afc-learned.md` now has ≥30 rules (count `<!-- afc:learned` markers), suggest consolidation:
+4. **Rule count check**: Suggest consolidation when the rules file becomes unwieldy — when rules overlap, contradict each other, or are too numerous to effectively guide behavior. Use judgment rather than a fixed count:
    ```
    afc-learned.md has {N} rules. Consider reviewing and consolidating related rules
    to keep context budget efficient. You can edit the file directly.
@@ -147,6 +147,6 @@ Learner review complete
 - **Opt-in only**: Learner signal collection requires `.claude/afc/learner.json` to exist. Run `/afc:learner enable` to start.
 - **Project-scoped rules**: All rules write to `.claude/rules/afc-learned.md` (git-tracked, team-visible). Never writes to root `CLAUDE.md`, `~/.claude/CLAUDE.md`, or auto memory.
 - **No raw prompts stored**: The signal queue contains only structured metadata (type, category, 80-char redacted excerpt, timestamp). Full prompt text is never persisted.
-- **Queue limits**: Max 50 entries, 7-day TTL. Stale entries are pruned at session start.
+- **Queue limits**: Manage queue size to prevent unbounded growth. Remove entries that have been reviewed, are no longer relevant (the code they reference has changed significantly), or are duplicates of already-processed patterns. As a practical guideline, keep the queue focused on recent, actionable items. Stale entries are pruned at session start.
 - **Safe by design**: Anti-injection guardrails prevent propagation of harmful instructions. Category blocklist prevents rules about permissions/security/hooks.
 - **Editable output**: `afc-learned.md` is a regular markdown file. Edit, delete, or reorganize rules at any time.

package/skills/plan/SKILL.md

@@ -119,7 +119,7 @@ After writing plan.md, verify all paths in the File Change Map:
 
 ### 5. Critic Loop
 
-> **Always** read `${CLAUDE_PLUGIN_ROOT}/docs/critic-loop-rules.md` first and follow it.
+> **Always** read `${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md` first and follow it.
 
 Run the critic loop until convergence. Safety cap: 5 passes.
 

package/skills/pr-comment/SKILL.md

@@ -134,10 +134,10 @@ No issues found. Code looks good!
 
 Display the full review comment to the user in the console.
 
-Then determine the review event type:
-- **Critical findings exist** → `REQUEST_CHANGES`
-- **Only Warning/Info findings** → `COMMENT`
-- **No findings** → `APPROVE`
+Then determine the review event based on the actual severity and context of findings:
+- **REQUEST_CHANGES**: Use when findings indicate genuine risk to production code — bugs that would affect users, security vulnerabilities, or architectural violations that would be costly to fix later. A Critical finding in test code or documentation alone does not warrant blocking the PR.
+- **COMMENT**: Use when findings are improvements or concerns that the author should consider but that don't pose immediate risk. Also appropriate when Critical findings are in non-production code (tests, docs, config) or when the author has already acknowledged the concern in PR discussion.
+- **APPROVE**: Use when no findings exist, or when all findings are informational and the code is ready to merge.
 
 Tell the user:
 ```

package/skills/principles/SKILL.md

@@ -107,5 +107,5 @@ Collect principles interactively:
 
 - **Persistent storage**: Saved to .claude/afc/memory/principles.md and maintained across sessions.
 - **Auto-referenced**: Automatically loaded and validated by /afc:plan and /afc:architect.
-- **Keep it concise**: Maintain no more than 10 principles. Too many reduces effectiveness.
+- **Keep it concise**: Keep principles concise and actionable. If the list grows long enough that principles start overlapping or becoming too granular, suggest consolidation. The goal is a set of principles that can be held in working memory — typically under 15, but the right number depends on the project's complexity.
 - **Avoid duplication with CLAUDE.md**: Do not re-register rules already present in CLAUDE.md as principles.

package/skills/qa/SKILL.md

@@ -82,7 +82,7 @@ Checks:
 Evaluate general code quality indicators.
 
 Checks:
-- **Complexity hotspots**: deeply nested logic, functions exceeding ~50 LOC
+- **Complexity hotspots**: deeply nested logic, functions with high cognitive complexity (many branches, side effects, or state mutations). Line count alone is not a reliable indicator — a 30-line function with nested conditionals and side effects may be more complex than a 60-line function with simple sequential logic.
 - **Duplication**: near-identical code blocks across files
 - **Magic numbers/strings**: unexplained literals in logic
 - **TODO/FIXME accumulation**: stale markers (count, age if git history available)
@@ -128,7 +128,7 @@ For each active category:
 
 ### 5. Critic Loop
 
-Apply `docs/critic-loop-rules.md` with **safety cap: 3 rounds**.
+**Always** read `${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md` first and follow it. Safety cap: **5 passes**.
 
 Focus the critic on:
 - Are the findings actionable or just noise?

package/skills/release-notes/SKILL.md

@@ -75,13 +75,17 @@ Flag any matches for the Breaking Changes section.
 
 Categorize each commit/PR into one of:
 
-| Category | Conventional Commit Prefixes | Fallback Heuristics |
-|----------|------------------------------|---------------------|
+| Category | Conventional Commit Prefixes | Fallback (no prefix) |
+|----------|------------------------------|----------------------|
 | Breaking Changes | `!:` suffix, `BREAKING` | Label: `breaking` |
-| New Features | `feat:` | "add", "new", "implement", "support" |
-| Bug Fixes | `fix:` | "fix", "resolve", "correct", "patch" |
+| New Features | `feat:` | Commit introduces new user-facing functionality |
+| Bug Fixes | `fix:` | Commit fixes broken or incorrect behavior |
 | Other Changes | `chore:`, `docs:`, `ci:`, `refactor:`, `perf:`, `test:`, `style:`, `build:` | Everything else |
 
+**Fallback classification rule** — For commits without conventional prefixes, read the commit message semantically. Classify based on what the commit actually does: did it introduce new user-facing functionality (New Features)? Did it fix broken behavior (Bug Fixes)? Or is it a maintenance/improvement change (Other Changes)? Do not match individual words — understand the commit's purpose.
+
+The word "add" in "add a new API endpoint" indicates a feature. The same word in "add missing test coverage" indicates a test (Other Changes). Context determines classification.
+
 **Rewriting rules** — transform each entry from developer-speak to user-facing language:
 
 1. Remove conventional commit prefixes (`feat:`, `fix(scope):`, etc.)

package/skills/review/SKILL.md

@@ -72,14 +72,14 @@ Before reviewing, identify **files affected by the changes** (not just the chang
 3. **Scope decision**:
    - Affected files are NOT full review targets (that would explode scope)
    - Instead, include them as **cross-reference context** in Step 2 and Step 3.5
-   - If an affected file has >3 references to a changed symbol → flag for closer inspection
+   - Flag affected files for closer inspection when they have significant coupling to the changed code — consider the nature of the references (type-only imports vs behavioral calls), the criticality of the affected file, and whether the references involve the specific symbols that changed.
 
 4. **Limitations** (include in review output):
    > ⚠ Dynamic dependencies not covered: runtime dispatch (`obj[method]()`), reflection, cross-language calls, config/env-driven branching. Manual verification recommended for these patterns.
 
 ### 2. Parallel Review (scaled by file count)
 
-Choose review orchestration based on the number of changed files:
+Assess review complexity holistically — consider total diff size (lines changed), file complexity, diversity of change types, and whether changes are localized to one module or cross-cutting across multiple boundaries.
 
 **Pre-scan: Call Chain Context** (for Parallel Batch and Review Swarm modes only):
 
@@ -97,21 +97,21 @@ Before distributing files to review agents, collect cross-boundary context:
    Review findings should account for these behaviors.
    ```
 
-For Direct review mode (≤5 files): skip pre-scan — orchestrator already has full context.
+For Direct review mode: skip pre-scan — orchestrator already has full context.
 
-#### 5 or fewer files: Direct review
-Review all files directly in the current context (no delegation).
+#### Low complexity: Direct review
+Appropriate when changes are small in total diff size, confined to a single module or area, and the reviewing model can hold all changed files in context without losing coherence. Review all files directly in the current context (no delegation).
 
-#### 6–10 files: Parallel Batch
-Distribute to parallel review agents (2–3 files per agent) in a **single message**:
+#### Moderate complexity: Parallel Batch
+Appropriate when changes span multiple files or modules, the total diff size is substantial, or different change types (e.g., API, UI, config) benefit from focused review segments. Distribute to parallel review agents (2–3 files per agent) in a **single message**:
 ```
 Task("Review: {file1, file2}", subagent_type: "general-purpose")
 Task("Review: {file3, file4}", subagent_type: "general-purpose")
 ```
 Read each agent's returned output, then write consolidated review.
 
-#### 11+ files: Review Swarm
-Create a review task pool and spawn pre-assigned review workers:
+#### High complexity: Review Swarm
+Appropriate when changes are large-scale, cross-cutting across many modules, involve mixed change types (security-sensitive code, architecture layers, business logic), or individual file groups require deep specialist focus. Create a review task pool and spawn pre-assigned review workers:
 
 > **Note**: Unlike implement swarm (which prohibits self-claiming due to write conflicts), review workers use orchestrator pre-assignment by file group. This is safe because review is read-only — no write race conditions.
 
@@ -204,9 +204,9 @@ For each changed file, examine from the following perspectives:
 
 After individual/parallel reviews complete, the **orchestrator** MUST perform a cross-boundary check. This is a required step, not optional — skipping it is a review defect.
 
-**For 11+ file reviews**: This is especially critical because individual review agents cannot see cross-file interactions. The orchestrator MUST read callee implementations directly.
+**For High complexity (Review Swarm) reviews**: This is especially critical because individual review agents cannot see cross-file interactions. The orchestrator MUST read callee implementations directly.
 
-0. **Impact Map integration**: Use the Impact Map from Step 1.5 to prioritize verification. Affected files with >3 references to changed symbols should be read and checked for breakage — even if no finding was raised against them.
+0. **Impact Map integration**: Use the Impact Map from Step 1.5 to prioritize verification. Affected files with significant coupling to changed symbols (behavioral call references, not just type imports, especially in critical code paths) should be read and checked for breakage — even if no finding was raised against them.
 
 1. **Filter**: From all collected findings, select those involving:
    - Call order changes (function A now calls B before C)
@@ -276,7 +276,7 @@ If `.claude/afc/memory/retrospectives/` directory exists, load the **most recent
 
 ### 6. Critic Loop
 
-> **Always** read `${CLAUDE_PLUGIN_ROOT}/docs/critic-loop-rules.md` first and follow it.
+> **Always** read `${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md` first and follow it.
 
 Run the critic loop until convergence. Safety cap: 5 passes.
 

package/skills/security/SKILL.md

@@ -41,11 +41,26 @@ For dependency audit command: infer from `packageManager` field in `package.json
 - `$ARGUMENTS` = "full" → entire `src/`
 - Not specified → changed files from `git diff --name-only HEAD`
 
-### 2. Agent Teams (if more than 10 files)
+### 2. Agent Teams (when scan complexity warrants it)
 
-Use parallel agents for wide-scope scans:
+Use Agent Teams when the scan scope is complex enough that a single-pass review would miss cross-file vulnerability patterns. Assess holistically:
 
-**Pre-scan: Data Flow Context** (before distributing to agents):
+- **File types**: Auth handlers, trust boundary code, and input-processing layers warrant deeper multi-agent scrutiny than config files or simple utilities
+- **Code volume**: Large files with dense logic benefit from focused agent attention
+- **Diversity of concerns**: Multiple distinct security domains (auth + injection + data exposure) across separate modules
+- **Trust boundaries**: Files that cross privilege levels (user input → DB, client → server, public → internal API)
+
+Use Agent Teams when any of the following apply:
+- Scan includes auth handlers, session management, or access control logic spanning multiple files
+- Input entry points and their sanitization/consumption code live in different directories
+- The scope spans multiple distinct security domains that cannot be assessed in a single coherent pass
+
+Use direct scan (orchestrator only) when:
+- Scope is a single module or tightly-coupled set of files
+- Security concerns are localized (e.g., one feature, one data flow)
+- No cross-file trust boundary transitions are involved
+
+**Pre-scan: Data Flow Context** (before distributing to agents, when using Agent Teams):
 
 1. For each changed file, identify **input entry points** (user input, API params, URL params, form data) and **sanitization calls** (validation, escaping, encoding)
 2. Trace input flow across changed files: where does user input enter? Where is it sanitized? Where is it consumed?
@@ -65,7 +80,7 @@ Task("Security scan: src/shared/api/", subagent_type: general-purpose,
   prompt: "... {include Data Flow Context} ...")
 ```
 
-For scans with ≤10 files: skip pre-scan — orchestrator has full context.
+For direct scans (orchestrator only): skip pre-scan — orchestrator has full context.
 
 ### 2.5. Cross-Boundary Verification