all-for-claudecode 2.10.0 → 2.12.0

package/skills/clarify/SKILL.md

@@ -50,10 +50,11 @@ Scan across 10 categories:
 | 9 | Completion criteria | Success criteria that cannot be measured |
 | 10 | Residual placeholders | TODO/TBD/??? |
 
+These categories serve as a comprehensive checklist, not a rigid classification. Adapt to the project's domain — skip categories irrelevant to the project type (e.g., skip 'UX flow' for CLI tools) and add domain-specific categories if needed (e.g., 'regulatory compliance' for healthcare/fintech projects).
+
 ### 3. Generate and Present Questions
 
-- Generate at most **5** questions
-- Priority: scope > security/privacy > UX > technical
+- Generate questions ranked by their impact on spec quality — how much would the answer change the spec's direction or completeness? Present the most impactful questions first. The number of questions should match the actual ambiguity level: deeply ambiguous specs may need more questions, while mostly-clear specs need fewer. Do not artificially cap at a fixed number, but keep the set focused and avoid overwhelming the user (aim for the minimum needed to resolve critical ambiguities).
 - Present **one at a time** via AskUserQuestion:
   - Use multiple choice when possible (2-4 options)
   - Include the meaning/impact of each option
@@ -79,7 +80,7 @@ Clarification complete
 
 ## Notes
 
-- **5-question limit**: If more than 5 questions arise, select only the most important. Resolve the rest during the plan phase.
+- **Question focus**: Ask only what is needed to resolve critical ambiguities. Defer lower-priority questions to the plan phase rather than overwhelming the user.
 - **Modify spec only**: Do not touch plan.md or tasks.md.
 - **Avoid redundancy**: Do not ask about items already clearly stated in spec.
 - **If `$ARGUMENTS` is provided**: Focus the scan on that area.

package/skills/clean/SKILL.md

@@ -24,7 +24,7 @@ model: sonnet
 ### 1. Resolve Feature
 
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" phase clean
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" phase clean
 ```
 
 - If pipeline is active: read feature from state
@@ -60,23 +60,24 @@ Set `PIPELINE_ARTIFACT_DIR` = `.claude/afc/specs/{feature}/`
 - **If retrospective.md exists** -> record as patterns missed by the Plan phase Critic Loop in `.claude/afc/memory/retrospectives/` (reuse as RISK checklist items in future runs)
 - **If review-report.md exists** -> copy to `.claude/afc/memory/reviews/{feature}-{date}.md` before .claude/afc/specs/ deletion
 - **If research.md exists** and was not already persisted in Plan phase -> copy to `.claude/afc/memory/research/{feature}.md`
-- **Agent memory consolidation**: check each agent's MEMORY.md line count -- if either exceeds 100 lines, invoke the respective agent to self-prune:
+- **Agent memory consolidation**: Check each agent's MEMORY.md for bloat — if it contains redundant, obsolete, or superseded entries that reduce signal-to-noise ratio, invoke the agent to self-prune:
   ```
   Task("Memory cleanup: afc-architect", subagent_type: "afc:afc-architect",
-    prompt: "Your MEMORY.md exceeds 100 lines. Read it, prune old/redundant entries, and rewrite to under 100 lines following your size limit rules.")
+    prompt: "Review your MEMORY.md. Read it, identify and prune old/redundant/obsolete entries, and rewrite it keeping only entries that are still relevant and non-overlapping.")
   ```
-  (Same pattern for afc-security if needed. Skip if both are under 100 lines.)
-- **Memory rotation**: for each memory subdirectory, check file count and prune oldest files if over threshold:
-  | Directory | Threshold | Action |
-  |-----------|-----------|--------|
-  | `quality-history/` | 30 files | Delete oldest files beyond threshold |
-  | `reviews/` | 40 files | Delete oldest files beyond threshold |
-  | `retrospectives/` | 30 files | Delete oldest files beyond threshold |
-  | `research/` | 50 files | Delete oldest files beyond threshold |
-  | `decisions/` | 60 files | Delete oldest files beyond threshold |
-  - Sort by filename ascending (oldest first), delete excess
+  Use semantic assessment (are entries still relevant? do entries overlap?) rather than a line-count threshold. (Same pattern for afc-security if needed.)
+- **Memory rotation**: For each memory subdirectory, assess whether the oldest files still provide value. Prune files that are superseded by newer entries, reference features/code that no longer exists, or overlap with other files. As a practical guideline, keep the most recent and relevant entries — if a directory has grown large enough that scanning it would be slow (roughly 30+ files), prioritize pruning the least relevant entries:
+  | Directory | Pruning Intent | Soft Guideline |
+  |-----------|---------------|----------------|
+  | `quality-history/` | Remove superseded or redundant quality records | ~30 files |
+  | `reviews/` | Remove reviews for features no longer in the codebase | ~40 files |
+  | `retrospectives/` | Remove retrospectives whose learnings are already captured elsewhere | ~30 files |
+  | `research/` | Remove research for libraries/patterns no longer used | ~50 files |
+  | `decisions/` | Remove decisions that have been reversed or are no longer relevant | ~60 files |
+  - These numbers are soft guidelines, not hard cutoffs — use judgment based on relevance
+  - Sort by filename ascending (oldest first) when pruning by recency
   - Log: `"Memory rotation: {dir} pruned {N} files"`
-  - Skip directories that do not exist or are under threshold
+  - Skip directories that do not exist or clearly do not need pruning
 
 ### 6. Quality Report
 
@@ -97,13 +98,13 @@ Clear `.claude/afc/memory/checkpoint.md` **and** `~/.claude/projects/{ENCODED_PA
 ### 8. Timeline Finalize
 
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" log pipeline-end "Pipeline complete: {feature}"
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" log pipeline-end "Pipeline complete: {feature}"
 ```
 
 ### 9. Release Pipeline Flag
 
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" end
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" end
 ```
 
 - Stop Gate Hook deactivated

package/skills/consult/SKILL.md

@@ -33,24 +33,25 @@ If `$ARGUMENTS` is empty → go to Step 2 (domain selection).
 
 **A. Explicit domain provided** → use it directly.
 
-**B. No domain, but question provided** → keyword matching:
-
-| Domain | Keywords |
-|--------|----------|
-| backend | API, database, schema, query, server, auth, JWT, REST, GraphQL, ORM, migration, endpoint, middleware, validation, session, cookie, token |
-| infra | deploy, Docker, CI/CD, cloud, monitoring, k8s, pipeline, Kubernetes, terraform, AWS, GCP, Azure, nginx, SSL, DNS, CDN, container, scaling |
-| pm | feature, user story, priority, roadmap, PRD, MVP, backlog, metric, KPI, retention, churn, persona, requirement, scope |
-| design | UI, UX, accessibility, component, layout, color, animation, responsive, wireframe, prototype, typography, spacing, contrast, WCAG |
-| marketing | SEO, analytics, content, growth, conversion, funnel, GA4, acquisition, retention, landing page, Open Graph, meta tag, social media |
-| legal | GDPR, CCPA, privacy, cookie, consent, license, GPL, MIT, compliance, terms of service, data protection, PII, HIPAA, regulation, policy |
-| security | XSS, CSRF, injection, OWASP, vulnerability, attack, exploit, encryption, secret, credential, CORS, CSP, rate limit, brute force, penetration |
-| advisor | library, framework, stack, tool, package, which to use, alternative, compare, choose, select, recommend, what exists, ecosystem, best option, switch to |
-| peer | think together, brainstorm, discuss, explore idea, talk through, figure out, pros and cons, what if, should I, direction, approach, trade-off, opinion, weigh options |
-
-Match rules:
-- Case-insensitive keyword matching against the question
-- If multiple domains match: pick the one with the most keyword hits
-- If tie: pick the first domain in the table order above
+**B. No domain, but question provided** → intent-based evaluation:
+
+Read the user's question and determine which domain's expertise would provide the most value. Consider the actual intent, not keyword presence.
+
+| Domain | When to route |
+|--------|---------------|
+| backend | User needs help with server-side logic, data modeling, API design, authentication flows, database decisions, or how application code processes and stores data |
+| infra | User needs help with how the application is deployed, operated, or monitored — infrastructure topology, CI/CD pipelines, cloud services, scaling, reliability |
+| pm | User needs help with product decisions: what to build, for whom, when, how to measure success, how to prioritize competing features, or how to define scope |
+| design | User needs help with how something looks or feels to a user — visual hierarchy, interaction patterns, accessibility, component design, or user flow |
+| marketing | User needs help reaching or retaining users outside the product: SEO, content strategy, acquisition funnels, analytics tracking, or growth tactics |
+| legal | User needs help understanding regulatory obligations, license compatibility, privacy requirements, or the legal implications of a design or data practice |
+| security | User needs help identifying or mitigating threats, vulnerabilities, or attack surfaces — secure coding, threat modeling, or compliance with security standards |
+| advisor | User is choosing between technologies, frameworks, libraries, or architectural approaches and wants an informed recommendation with trade-off analysis |
+| peer | User wants to think through a problem collaboratively, explore directions, weigh trade-offs, or have a structured dialogue rather than receive an answer |
+
+Evaluation rules:
+- Identify what specialized knowledge the user actually needs, not which domain's jargon appears in the text
+- If multiple domains seem relevant, identify the PRIMARY expertise gap — what specialized knowledge does the user need most?
 
 **C. No domain, no question, or no keyword match** → ask user:
 

package/skills/debug/SKILL.md

@@ -86,7 +86,7 @@ If hypothesis 0 is rejected: verify remaining hypotheses starting from highest p
 
 ### 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/doctor/SKILL.md

@@ -16,7 +16,7 @@ model: sonnet
 > Like `brew doctor` or `flutter doctor` — verifies the **tool's setup**, NOT the project's code quality.
 > Read-only — never modifies files. Reports issues with actionable fix commands.
 >
-> **IMPORTANT: Do NOT analyze project source code, architecture, or code quality. Only check afc plugin configuration, hooks, state, and environment as defined in the check tables below.**
+> **IMPORTANT: Do NOT analyze project source code, architecture, or code quality. Only check afc plugin configuration, hooks, state, and environment. All checks are handled by the bash script — just run it and print the output.**
 
 ## Arguments
 
@@ -39,7 +39,7 @@ Each failing check includes a **Fix:** line with the exact command to resolve it
 
 1. Run the health check script (covers ALL categories — no manual checks needed):
    ```
-   "${CLAUDE_PLUGIN_ROOT}/scripts/afc-doctor.sh" $ARGUMENTS
+   "${CLAUDE_SKILL_DIR}/../../scripts/afc-doctor.sh" $ARGUMENTS
    ```
 
 2. Print the script's stdout output as-is. Do not reformat, summarize, or interpret.
@@ -54,8 +54,8 @@ Each failing check includes a **Fix:** line with the exact command to resolve it
 ## Example Output
 
 ```
-all-for-claudecode Doctor
-=======================
+all-for-claudecode Doctor (v2.11.0)
+Plugin root: /path/to/plugin
 
 Environment
   ✓ git installed (2.43.0)
@@ -64,34 +64,38 @@ Environment
 
 Project Config
   ✓ .claude/afc.config.md exists
-  ✓ Required sections: ci, gate, architecture, code_style
-  ✓ CI command runnable
-  ✓ Gate command runnable
+  ✓ Required sections present
+  ✓ Gate command defined
 
 CLAUDE.md Integration
   ✓ Global ~/.claude/CLAUDE.md exists
   ✓ all-for-claudecode block present
-  ⚠ all-for-claudecode block version outdated (1.0.0 → 1.1.0)
-    Fix: /afc:init
-  ✓ No conflicting routing
+  ⚠ all-for-claudecode block outdated (block: 1.0.0, plugin: 1.1.0)
+    Fix: run /afc:setup to update
+
+Legacy Migration
+  ✓ No legacy artifacts found
 
 Pipeline State
-  ✓ No stale pipeline flag
+  ✓ No stale pipeline state
   ✓ No orphaned artifacts
-  ✓ No lingering safety tags
-  ✓ No stale checkpoint
+
+Memory Health
 
 Hook Health
   ✓ hooks.json valid
-  ✓ All scripts exist
+  ✓ All hook scripts exist
   ✓ All scripts executable
 
+Learner Health
+  ✓ Learner not enabled (opt-in via /afc:learner enable)
+
 Version Sync (dev)
-  ✓ Version triple match
+  ✓ Version triple match (1.1.0)
   ✓ Cache in sync
 
-Command Definitions (dev)
-  ✓ Frontmatter exists (25 files)
+Skill Definitions (dev)
+  ✓ Frontmatter exists (29 files)
   ✓ Required fields present
   ✓ Name-filename match
   ✓ Fork-agent references valid
@@ -108,7 +112,7 @@ Doc References (dev)
   ✓ Domain adapters exist (3 files)
 
 ─────────────────────────
-Results: 28 passed, 2 warnings, 0 failures
+Results: 26 passed, 2 warnings, 0 failures
 2 warnings found. Non-blocking but review recommended.
 ```
 
@@ -119,4 +123,4 @@ Results: 28 passed, 2 warnings, 0 failures
 - **Always run all checks**: do not stop on first failure. The full picture is the value.
 - **Actionable fixes**: every non-pass result must include a Fix line. Never report a problem without a solution.
 - **Fast execution**: skip CI/gate command checks if `--fast` is in arguments (these are the slowest checks).
-- **Development checks**: Categories 8–11 (Version Sync, Command Definitions, Agent Definitions, Doc References) only run when inside the all-for-claudecode source repo.
+- **Development checks**: Version Sync, Skill Definitions, Agent Definitions, Doc References only run when inside the all-for-claudecode source repo.

package/skills/implement/SKILL.md

@@ -43,8 +43,8 @@ git tag -f afc/pre-implement
 **Standalone safety activation** (skip if inside `/afc:auto`):
 If no active pipeline state exists, activate it for the duration of this command:
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" start {feature-name-from-plan.md}
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" phase implement
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" start {feature-name-from-plan.md}
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" phase implement
 ```
 This enables Stop Gate and CI Gate hooks during standalone implementation. Release on completion (Step 7) or failure rollback.
 
@@ -81,8 +81,8 @@ If `.claude/afc/specs/{feature}/tasks.md` does not exist, generate it from plan.
      - Constraint → tasks (every spec Constraint is addressed by at least one task)
 3. **Validate** (script-based, no critic loop):
    ```bash
-   "${CLAUDE_PLUGIN_ROOT}/scripts/afc-dag-validate.sh" .claude/afc/specs/{feature}/tasks.md
-   "${CLAUDE_PLUGIN_ROOT}/scripts/afc-parallel-validate.sh" .claude/afc/specs/{feature}/tasks.md
+   "${CLAUDE_SKILL_DIR}/../../scripts/afc-dag-validate.sh" .claude/afc/specs/{feature}/tasks.md
+   "${CLAUDE_SKILL_DIR}/../../scripts/afc-parallel-validate.sh" .claude/afc/specs/{feature}/tasks.md
    ```
 4. If validation fails → fix tasks.md and re-validate (max 2 attempts)
 5. Save to `.claude/afc/specs/{feature}/tasks.md`
@@ -116,7 +116,7 @@ If `.claude/afc/memory/retrospectives/` exists, load the **most recent 10 files*
 
 ### 3. Phase-by-Phase Execution
 
-Execute each phase in order. Choose the orchestration mode based on the number of [P] tasks in the phase:
+Execute each phase in order. Choose the orchestration mode by evaluating whether multi-agent coordination overhead would be justified given the tasks' characteristics:
 
 #### Mode Selection
 
@@ -126,12 +126,17 @@ Execute each phase in order. Choose the orchestration mode based on the number o
 |-----------|------|----------|
 | No [P] markers | Sequential | Main agent executes tasks one by one |
 | [P] tasks but delegation criteria NOT met | Sequential | Main agent executes directly (preserves full context) |
-| [P] tasks, delegation criteria ALL met, 3–5 [P] | Parallel Batch | Launch Task() calls in parallel |
-| [P] tasks, delegation criteria ALL met, 6+ [P] | Swarm | Create task pool → orchestrator pre-assigns tasks to worker agents |
+| [P] tasks, delegation criteria ALL met, coordination overhead justified, moderate parallelism | Parallel Batch | Launch Task() calls in parallel |
+| [P] tasks, delegation criteria ALL met, coordination overhead clearly justified, high parallelism | Swarm | Create task pool → orchestrator pre-assigns tasks to worker agents |
+
+**Mode judgment**: Ask — "Given these N tasks with their complexity, file scope, and interdependencies, would spawning multiple agents and merging their results be faster and safer than executing sequentially?" If the answer is not clearly yes, default to Sequential.
+
+- **Parallel Batch** is appropriate when there are enough independent tasks that parallel execution provides meaningful speed gain, but the total count is manageable enough that a single orchestrator round-trip suffices.
+- **Swarm** is appropriate when the number of independent tasks is large enough that a single batch of Task() calls would saturate the concurrent agent limit, requiring multiple orchestrator rounds.
 
 **Parallel delegation criteria** (ALL must be satisfied):
 1. Tasks have **no `depends:` edges** between them in the DAG (no ordering constraint)
-2. **≥ 3 parallelizable tasks** in the phase (2 tasks → sequential is cheaper)
+2. **Enough parallelizable tasks** that multi-agent overhead is worth it (a very small number of short tasks → sequential is cheaper)
 3. Each task is **self-contained** (does not require runtime results from other tasks in the same batch)
 4. Each task's **target files do not overlap** with any other task in the batch (no shared file writes)
 
@@ -143,7 +148,7 @@ If ANY criterion fails → main agent sequential execution (context preservation
 - On task start: `▶ {ID}: {description}`
 - On completion: `✓ {ID} complete`
 
-#### Parallel Batch Mode (3–5 [P] tasks)
+#### Parallel Batch Mode (moderate [P] tasks)
 
 **Pre-validation**: Verify no file overlap (downgrade to sequential if overlapping).
 
@@ -203,14 +208,18 @@ Task("T004: Create AuthService", subagent_type: "afc:afc-impl-worker", isolation
 2. Capture the `agentId` from the failed agent's result (returned in Task tool output)
 3. Reset: `TaskUpdate(taskId, status: "pending")`
 4. Track: `TaskUpdate(taskId, metadata: { retryCount: N, lastAgentId: agentId })`
-5. If retryCount < 3 → re-launch with `resume: lastAgentId` in the next batch round. The resumed agent retains full context from the previous attempt (what it tried, what failed, partial progress), enabling more targeted retry instead of starting from scratch.
+5. **Classify the error before deciding to retry**:
+   - **First failure** (no `metadata.lastError` exists): store `metadata.lastError = {current error message}`. Classify as transient (no prior error to compare) and proceed with retry.
+   - **Subsequent failures** (`metadata.lastError` exists): Compare the current error with `metadata.lastError`. If the error is **the same** (deterministic failure — same message, same stack location) → stop immediately and mark as failed. Retrying a deterministic failure wastes cycles.
+   - If the error **differs** from the previous attempt (transient/flaky — different message, network blip, lock contention) → re-launch with `resume: lastAgentId`. The resumed agent retains full context from the previous attempt (what it tried, what failed, partial progress), enabling more targeted retry.
    - **Worktree caveat**: if the failed worker made no file changes, its worktree is auto-cleaned and `resume` will fail. In this case, fall back to a fresh launch (omit `resume`) for the retry.
-6. If retryCount >= 3 → mark as failed, report: `"T{ID} failed after 3 attempts: {last error}"`
+   - Update `metadata.lastError` with the current error on each attempt.
+6. If retryCount >= 5 (absolute safety cap) → mark as failed, report: `"T{ID} failed after {retryCount} attempts: {last error}"`
 7. Continue with remaining tasks — a single failure does not block the entire phase
 
-#### Swarm Mode (6+ [P] tasks)
+#### Swarm Mode (high [P] task count)
 
-When a phase has more than 5 parallelizable tasks, use the **orchestrator-managed swarm pattern**.
+When a phase has enough parallelizable tasks that a single batch of Task() calls would saturate the concurrent agent limit and require multiple orchestrator rounds, use the **orchestrator-managed swarm pattern**.
 
 > **Key constraint**: Claude Code's TaskUpdate uses **last-write-wins** with local file locking only. Multiple sub-agents calling TaskUpdate on the same task simultaneously can cause lost writes. The orchestrator must mediate task assignment to prevent collisions.
 
@@ -268,7 +277,7 @@ Task("Worker 2: T008, T010, T012", subagent_type: "afc:afc-impl-worker", isolati
 5. If unblocked tasks remain → assign to new worker batch (repeat Step 2)
 6. If all tasks complete → phase done
 
-**Worker count**: N = min(5, unblocked task count). Max 5 concurrent sub-agents per phase.
+**Worker count**: N = min(5, unblocked task count). Max 5 concurrent sub-agents per phase (5 is the Claude Code platform limit for concurrent agents — not a semantic preference).
 
 **Task assignment strategy**: Round-robin by file path — each worker gets tasks targeting different files to maximize isolation. If a worker has multiple tasks, order them by `depends:` topology.
 
@@ -280,9 +289,13 @@ When a worker agent returns an error:
 3. Capture the `agentId` from the failed worker's result
 4. Reset uncompleted tasks: `TaskUpdate(taskId, status: "pending")`
 5. Track retry count: `TaskUpdate(taskId, metadata: { retryCount: N, lastAgentId: agentId })`
-6. If retryCount < 3 → re-launch with `resume: lastAgentId` to preserve context from the previous attempt. The resumed agent retains its full conversation history (files read, changes attempted, errors encountered), enabling targeted retry.
+6. **Classify the error before deciding to retry**:
+   - **First failure** (no `metadata.lastError` exists): store `metadata.lastError = {current error message}`. Classify as transient (no prior error to compare) and proceed with retry.
+   - **Subsequent failures** (`metadata.lastError` exists): Compare the current error with `metadata.lastError`. If the error is **the same** (deterministic failure — same message, same stack location) → stop immediately and mark as failed. Retrying a deterministic failure wastes cycles.
+   - If the error **differs** from the previous attempt (transient/flaky — different message, network blip, lock contention) → re-launch with `resume: lastAgentId`. The resumed agent retains its full conversation history (files read, changes attempted, errors encountered), enabling targeted retry.
    - **Worktree caveat**: if the failed worker made no file changes, its worktree is auto-cleaned and `resume` will fail. In this case, fall back to a fresh launch (omit `resume`) for the retry.
-7. If retryCount >= 3 → mark as failed, report: `"T{ID} failed after 3 attempts: {last error}"`
+   - Update `metadata.lastError` with the current error on each attempt.
+7. If retryCount >= 5 (absolute safety cap) → mark as failed, report: `"T{ID} failed after {retryCount} attempts: {last error}"`
 8. Continue with remaining tasks
 
 > Single task failure does not block the phase. The orchestrator reassigns failed tasks to subsequent batches.
@@ -299,12 +312,12 @@ When a worker agent returns an error:
 
 #### Phase Completion Gate (3 steps)
 
-> **Always** read `${CLAUDE_PLUGIN_ROOT}/docs/phase-gate-protocol.md` first and perform the 3–4 steps (CI gate → Mini-Review → Integration/E2E Gate (conditional) → Auto-Checkpoint) in order.
+> **Always** read `${CLAUDE_SKILL_DIR}/../../docs/phase-gate-protocol.md` first and perform the 3–4 steps (CI gate → Mini-Review → Integration/E2E Gate (conditional) → Auto-Checkpoint) in order.
 > Cannot advance to the next phase without passing the gate. Abort and report to user after 3 consecutive CI failures.
 
 After passing the gate, create a phase rollback point:
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" phase-tag {phase_number}
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" phase-tag {phase_number}
 ```
 This enables granular rollback: `git reset --hard afc/phase-{N}` restores state after Phase N completed.
 
@@ -346,11 +359,11 @@ After all tasks are complete:
 
 After CI passes, run a convergence-based Critic Loop to verify design alignment before reporting completion.
 
-> **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.
 
 **Critic Loop until convergence** (safety cap: 5):
 
-- **SCOPE_ADHERENCE**: Compare `git diff` changed files against plan.md File Change List. Flag any file modified that is NOT in the plan. Flag any planned file NOT modified. Provide "M of N files match" count.
+- **SCOPE_ADHERENCE**: Compare `git diff` changed files against plan.md File Change Map. Flag any file modified that is NOT in the plan. Flag any planned file NOT modified. Provide "M of N files match" count.
 - **ARCHITECTURE**: Validate changed files against `{config.architecture}` rules (layer boundaries, naming conventions, import paths). Provide "N of M rules checked" count.
 - **CORRECTNESS**: Cross-check implemented changes against spec.md acceptance criteria (AC). Verify each AC has corresponding code. Provide "N of M AC verified" count.
 - **SIDE_EFFECT_SAFETY**: For tasks that changed call order, error handling, or state flow: verify that callee behavior is compatible with the new call pattern. Provide "{M} of {N} behavioral changes verified" count.
@@ -365,7 +378,7 @@ After CI passes, run a convergence-based Critic Loop to verify design alignment
 
 **Standalone cleanup** (if pipeline was activated in Step 0):
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" end
+"${CLAUDE_SKILL_DIR}/../../scripts/afc-pipeline-manage.sh" end
 ```
 
 ```
@@ -384,10 +397,10 @@ Implementation complete
 - **Architecture compliance**: follow {config.architecture} rules.
 - **{config.ci} gate**: must pass on phase completion. Do not bypass.
 - **Swarm workers**: max 5 concurrent. File overlap is strictly prohibited between parallel tasks.
-- **On error**: prevent infinite loops. Report to user after 3 attempts.
+- **On error**: classify errors before retrying. Stop immediately on deterministic (same) errors. Allow additional attempts for transient (different) errors. Hard cap at 5 retries total.
 - **Real-time tasks.md updates**: mark checkbox on each task completion.
 - **Default is direct execution**: main agent executes tasks directly unless all 4 parallel delegation criteria are met. This preserves full context and avoids multi-agent context loss.
-- **Mode selection is automatic**: do not manually override. Sequential (default), batch for 3–5 qualifying [P], swarm for 6+ qualifying [P].
+- **Mode selection is automatic**: do not manually override. Sequential (default), batch when moderate independent parallelism justifies coordination overhead, swarm when high task count requires multiple orchestrator rounds.
 - **NEVER use `run_in_background: true` on Task calls**: agents must run in foreground so results are returned before the next step.
 - **No worker self-claiming**: In swarm mode, the orchestrator pre-assigns tasks to workers. Workers do NOT call TaskList/TaskUpdate to claim tasks — this avoids last-write-wins race conditions on TaskUpdate.
 - **Phase-locked registration**: Only register (TaskCreate) the current phase's tasks. Never pre-register future phases. This is the primary mechanism for phase boundary enforcement.