all-for-claudecode 2.13.0 → 2.14.0

package/skills/auto/skill-advisor.md

@@ -0,0 +1,306 @@
+# Skill Advisor — Reference
+
+> Invoked by `/afc:auto` at 5 phase-boundary checkpoints. Each checkpoint uses LLM semantic evaluation (not keyword matching) to determine whether auxiliary skills add value. Budget-controlled: max 5 auxiliary invocations per pipeline.
+
+## Execution Modes
+
+| Mode | Description | Context cost |
+|------|-------------|-------------|
+| **Transform** | Skill output replaces/restructures the next phase's input | High (blocking) |
+| **Enrich** | Skill output appends context to the next phase's input | Low (fork/Task) |
+| **Observe** | Skill output is metadata only (logged, flags set) | Low (fork) |
+
+**Result recording**: After every advisor skill completes (any mode), append a brief summary to `.claude/afc/specs/{feature}/context.md` using the format defined at each checkpoint. This ensures advisor insights survive context compaction and are available to all subsequent phases.
+
+## Budget Control
+
+| Constraint | Limit | Rationale |
+|-----------|-------|-----------|
+| Per checkpoint | max 2 skills | Phase transition delay cap |
+| Pipeline total | max 5 auxiliary invocations | Total execution time cap |
+| Transform mode | max 1 per pipeline | Main context pollution prevention |
+| Concurrent fork | max 3 per checkpoint | Agent resource limit |
+
+Track in `ADVISOR_COUNT` (starts 0) and `ADVISOR_TRANSFORM_USED` (boolean). Persist every increment:
+```bash
+afc_state_write "advisorCount" "$ADVISOR_COUNT"
+afc_state_write "advisorTransformUsed" "true"  # when Transform is used
+```
+On context recovery: `ADVISOR_COUNT = afc_state_read "advisorCount"`.
+
+## Expert Agent Routing
+
+Route based on what expertise the feature actually needs (not keyword presence). Verify domain relevance against `{config.architecture}` — skip inapplicable domains (e.g., `design` for CLI, `infra` for no-deployment project).
+
+| Domain | Agent ID (subagent_type value) | When to route |
+|--------|-------------------------------|---------------|
+| backend | `afc-backend-expert` | API design, database schema, server architecture, auth flows |
+| infra | `afc-infra-expert` | Deployment, CI/CD, cloud infrastructure, containerization |
+| pm | `afc-pm-expert` | Product decisions, user stories, prioritization, metrics |
+| design | `afc-design-expert` | UI/UX, accessibility, component design, visual hierarchy |
+| marketing | `afc-marketing-expert` | SEO, analytics, growth, conversion optimization |
+| legal | `afc-legal-expert` | Privacy regulations, licensing, compliance, data protection |
+| security | `afc-appsec-expert` | Application security, vulnerability patterns, secure coding |
+| advisor | `afc-tech-advisor` | Technology selection, library comparison, stack decisions |
+
+**Important**: Use the Agent ID column as the `subagent_type` value directly (e.g., `subagent_type: "afc:afc-backend-expert"`). `security` → `afc-appsec-expert` (NOT `afc-security-expert`).
+
+---
+
+## Checkpoint A — Pre-Spec
+
+> Fire BEFORE Phase 1 (Spec). Skip if `ADVISOR_COUNT >= 5`. Budget: max 2 skills, max 1 Transform.
+
+| # | Question | Score 1–5 | If >= 3 | Skill | Mode |
+|---|----------|-----------|---------|-------|------|
+| A1 | Is this request at the **idea/vision level** rather than a concrete feature? (lacks specific file paths, API endpoints, component names) | 1=concrete spec-ready, 5=pure vision | `ideate` | Transform |
+| A2 | Does implementing this feature require **specialized domain knowledge** that a generalist developer wouldn't have? (regulatory, industry-specific patterns, compliance) | 1=general programming, 5=deep domain expertise essential | `consult({domain})` | Enrich (fork) |
+
+**If A1 >= 3** (Transform — skip if `ADVISOR_TRANSFORM_USED`):
+1. Execute `/afc:ideate` inline with `$ARGUMENTS`
+2. On failure: do NOT set `ADVISOR_TRANSFORM_USED`, proceed with original `$ARGUMENTS`, log: `"Skill Advisor [A]: ideate failed, proceeding with original input"`
+3. On success: extract `## Problem Statement` + `## Value Proposition` + `## Core Features (MoSCoW)` (Must Have only) from `ideate.md`
+4. Construct enriched spec input:
+   ```
+   SPEC_INPUT = "$ARGUMENTS
+
+   ## Ideation Context (auto-generated)
+   {extracted Problem Statement}
+   {extracted Value Proposition}
+   {extracted Core Features — Must Have only}"
+   ```
+5. Replace `$ARGUMENTS` with `SPEC_INPUT` for Phase 1. Set `ADVISOR_TRANSFORM_USED = true`, increment `ADVISOR_COUNT`, persist both to state.
+6. Progress: `  ├─ Skill Advisor [A]: ideate (score: {N}/5, input restructured from idea to structured brief)`
+
+**If A2 >= 3** (Enrich):
+1. Determine which domain best matches the actual expertise gap (not keywords). Verify relevance against project tech stack.
+2. Invoke expert agent:
+   ```
+   Task("Domain pre-consultation: {domain}", subagent_type: "afc:{agent-id}",
+     prompt: "You are being consulted automatically during pipeline spec preparation.
+     ## Feature Context
+     {$ARGUMENTS}
+     ## Why You Were Consulted
+     {1-sentence explanation of expertise gap}
+     ## Instructions
+     1. Read your MEMORY.md for prior project context
+     2. Read .claude/afc/project-profile.md if it exists
+     3. Provide domain-specific constraints and anti-patterns that MUST be reflected in the spec
+     4. Format EXACTLY as:
+        ## Domain Constraints ({domain})
+        - [MUST] {constraint}: {rationale}
+        - [MUST NOT] {anti-pattern}: {risk}
+        - [CONSIDER] {best practice}: {benefit}
+     5. Max 10 items, prioritized by risk severity.
+     6. Update your MEMORY.md with the consultation context")
+   ```
+3. Store as `DOMAIN_CONSTRAINTS` → inject into Phase 1. Spec MUST include `## Domain Constraints` section.
+4. Increment `ADVISOR_COUNT`. Progress: `  ├─ Skill Advisor [A]: consult({domain}) (score: {N}/5, {M} constraints injected)`
+
+---
+
+## Checkpoint B — Post-Spec
+
+> Fire AFTER Phase 1, BEFORE Phase 2 (Plan). Skip if `ADVISOR_COUNT >= 5`. Budget: max 2 skills.
+
+| # | Question | Score 1–5 | If >= 3 | Skill | Mode |
+|---|----------|-----------|---------|-------|------|
+| B1 | Does this feature **handle, store, or transmit sensitive data or trust boundaries**? (auth/authz, PII, financial data, external input reaching internal systems, session/token lifecycle) | 1=no trust boundary touched, 5=core security feature | `security` | Enrich (fork) |
+| B2 | Does this feature **cross multiple architectural boundaries** or introduce a new structural pattern? (3+ layers, new component type, coordination across independently-deployable units) | 1=single-layer change, 5=cross-cutting architectural change | `architect` | Enrich (fork) |
+
+**If B1 >= 3** (Enrich):
+1. Invoke security agent for pre-plan threat modeling:
+   ```
+   Task("Threat Model: {feature}", subagent_type: "afc:afc-security",
+     prompt: "Generate a threat model BEFORE implementation planning begins.
+     ## Spec Summary
+     {spec.md FR/NFR/Key Entities — security-relevant items only}
+     ## Why This Was Triggered
+     {1-sentence explanation}
+     ## Instructions
+     1. Read your MEMORY.md for known vulnerability patterns in this project
+     2. Identify attack surfaces from spec requirements
+     3. Format EXACTLY as:
+        ## Threat Model (pre-scan)
+        | Threat | Attack Surface | Mitigation Required | Priority |
+        |--------|---------------|-------------------|----------|
+     4. Max 8 threats, prioritized by exploitability and impact.")
+   ```
+2. Store as `THREAT_MODEL` → inject into Phase 2. Plan MUST address each mitigation in Risk & Mitigation. Plan Critic RISK criterion MUST verify: `{M}/{N} threat mitigations addressed`.
+3. Increment `ADVISOR_COUNT`. Progress: `  ├─ Skill Advisor [B]: security (score: {N}/5, threat model: {M} threats identified)`
+
+**If B2 >= 3** (Enrich):
+1. Invoke architect agent for pre-plan guidance:
+   ```
+   Task("Architecture Advisory: {feature}", subagent_type: "afc:afc-architect",
+     prompt: "Provide architecture guidance BEFORE plan creation.
+     ## Spec Summary
+     {spec.md Key Entities + layer analysis from {config.architecture}}
+     ## Why This Was Triggered
+     {1-sentence explanation}
+     ## Instructions
+     1. Read your MEMORY.md for prior ADRs and architecture patterns
+     2. Recommend: component placement, layer boundaries, interface contracts
+     3. Flag conflicts with existing architecture patterns
+     4. Format EXACTLY as:
+        ## Architecture Advisory (pre-plan)
+        - [PLACE] {component} → {layer/module}: {rationale}
+        - [BOUNDARY] {interface}: {contract description}
+        - [CONFLICT] {existing} ↔ {new}: {resolution recommendation}
+        - [PATTERN] {recommended pattern}: {why it fits}
+     5. Max 10 items. Update your MEMORY.md if new patterns are identified")
+   ```
+2. Store as `ARCH_ADVISORY` → inject into Phase 2. Plan Critic ARCHITECTURE criterion MUST validate against this advisory.
+3. Increment `ADVISOR_COUNT`. Progress: `  ├─ Skill Advisor [B]: architect (score: {N}/5, advisory: {M} recommendations, {K} conflicts)`
+
+**If both B1 and B2 >= 3**: launch both agents in a **single message** (parallel fork). After both return, apply `THREAT_MODEL` and `ARCH_ADVISORY` to plan. If mitigations conflict with architecture proposals → **ESCALATE** to user with conflict details.
+
+---
+
+## Checkpoint C — Post-Plan
+
+> Fire AFTER Phase 2, BEFORE Phase 3 (Implement). Skip if `ADVISOR_COUNT >= 5`. Budget: max 2 skills.
+
+| # | Question | Score 1–5 | If >= 3 | Skill | Mode |
+|---|----------|-----------|---------|-------|------|
+| C1 | Is **implementation risk high enough** that dependency pre-analysis would catch problems the plan missed? (files importing each other, high fan-out shared utils, incomplete `Depends On` relationships, hidden coupling) | 1=isolated changes, 5=deeply interconnected change set | dependency analysis (general-purpose fork) | Observe |
+| C2 | Does the plan contain **unresolved domain uncertainties** — items tagged `[UNCERTAIN]`, open questions in Implementation Context, design decisions assuming domain knowledge the team may lack? | 1=all decisions well-grounded, 5=critical domain questions remain open | `consult({domain})` expert agent | Enrich (fork) |
+
+**If C1 >= 3** (Observe):
+1. Invoke analysis in fork context:
+   ```
+   Task("Complexity Analysis: {feature}", subagent_type: "general-purpose",
+     prompt: "Analyze the dependency graph of files listed in the plan's File Change Map.
+     ## File Change Map
+     {paste File Change Map table from plan.md}
+     ## Instructions
+     1. For each file, check imports/dependencies (Grep for import/require/source patterns)
+     2. Identify:
+        - Circular dependencies between planned files
+        - High fan-out files (>5 dependents outside the change set)
+        - Hidden coupling not captured in Depends On column
+        - Files imported by many others (risk of breakage)
+     3. Format EXACTLY as:
+        ## Complexity Analysis
+        - [CIRCULAR] {file A} ↔ {file B}: {description}
+        - [FAN-OUT] {file} → {N} dependents: {list top 5}
+        - [COUPLING] {file A} → {file B}: {not in Depends On column}
+        - [HIGH-RISK] {file}: {reason}
+        ## Risk Summary
+        Circular: {N}, High fan-out: {N}, Hidden coupling: {N}
+     4. If no issues: '## Complexity Analysis\nNo significant risks detected.'")
+   ```
+2. Store to `.claude/afc/specs/{feature}/complexity-analysis.md`. Implement phase reads this — high-risk files get extra verification after modification. Circular dependencies → **ESCALATE** to user.
+3. Increment `ADVISOR_COUNT`. Progress: `  ├─ Skill Advisor [C]: analyze (score: {N}/5, circular: {C}, fan-out: {F}, coupling: {H})`
+
+**If C2 >= 3** (Enrich):
+1. Determine which domain expert best resolves the uncertainties. Invoke:
+   ```
+   Task("Domain gap resolution: {domain}", subagent_type: "afc:{agent-id}",
+     prompt: "Resolve domain uncertainties found during planning.
+     ## Uncertain Items
+     {extract all [UNCERTAIN] tagged items and open questions from plan.md}
+     ## Plan Context
+     {Implementation Context section from plan.md}
+     ## Instructions
+     1. For each uncertain item, provide a definitive answer with rationale
+     2. Format EXACTLY as:
+        ## Domain Resolutions
+        - [RESOLVED] {item}: {answer} — {rationale}
+        - [NEEDS-USER] {item}: {why this requires human judgment}
+     3. Update your MEMORY.md with the resolution context")
+   ```
+2. Apply resolutions to plan.md (replace `[UNCERTAIN]` with `[RESOLVED: {answer}]`). `[NEEDS-USER]` → **ESCALATE** via AskUserQuestion.
+3. Increment `ADVISOR_COUNT`. Progress: `  ├─ Skill Advisor [C]: consult({domain}) (score: {N}/5, {M} resolved, {K} needs-user)`
+
+---
+
+## Checkpoint D — Post-Implement
+
+> Fire AFTER Phase 3, BEFORE Phase 4 (Review). Skip if `ADVISOR_COUNT >= 5`. Budget: max 2 skills.
+
+| # | Question | Score 1–5 | If >= 3 | Skill | Mode |
+|---|----------|-----------|---------|-------|------|
+| D1 | Were **testable source files changed without corresponding test coverage**? (check `git diff --name-only` — skip config, types-only, static assets; only evaluate if `{config.test}` is non-empty) | 1=all changes have test coverage, 5=critical logic changed with zero tests | test generation (general-purpose fork) | Enrich |
+| D2 | Based on **past pipeline quality data**, is there reason to believe this implementation has hidden quality issues? (check `.claude/afc/memory/quality-history/*.json` for elevated critical findings or recurring problem categories) | 1=clean history or no history, 5=strong pattern of recurring issues in similar areas | pre-review QA (general-purpose fork) | Observe |
+
+**If D1 >= 3 AND `{config.test}` is non-empty** (Enrich):
+1. For each changed source file: does the project have a test file for it? Was it also modified in this diff? Does it contain testable exports?
+2. Invoke test generation:
+   ```
+   Task("Coverage boost: {feature}", subagent_type: "general-purpose",
+     prompt: "Generate missing tests for recently implemented files.
+     ## Uncovered Files
+     {list of source files with testable logic but no test changes in this diff}
+     ## Instructions
+     1. Read each uncovered file to understand exports and behavior
+     2. Read existing test files for pattern reference
+     3. Generate unit tests targeting exported functions/classes, edge cases, error paths, integration points
+     4. Follow project test framework: {config.test framework}
+     5. Place test files following project convention
+     6. Run {config.test} to verify tests pass
+     7. Return: files created, test count, pass/fail status")
+   ```
+3. New test files automatically enter review scope. Increment `ADVISOR_COUNT`.
+4. Progress: `  ├─ Skill Advisor [D]: test (score: {N}/5, {M} uncovered files → {K} test files generated)`
+
+**If D2 >= 3** (Observe):
+1. Load `.claude/afc/memory/quality-history/*.json` (most recent 3 files):
+   ```
+   Task("Pre-review QA: {feature}", subagent_type: "general-purpose",
+     prompt: "Perform a pre-review quality audit focused on historically problematic areas.
+     ## Changed Files
+     {git diff --name-only}
+     ## Quality History Context
+     {summary of patterns from recent quality-history reports}
+     ## Instructions
+     1. Focus on recurring problem categories
+     2. Check: error handling completeness, input validation, resource cleanup
+     3. Format EXACTLY as:
+        ## Pre-Review QA Findings
+        - [{severity}] {file}:{line} — {issue}: {suggested fix}
+        ## Priority Hints for Review
+        - {file}: focus on {area} (historically problematic)
+     4. Read-only — do NOT modify any files")
+   ```
+2. Store as `QA_FINDINGS` → inject into Phase 4 as Priority Hints. Increment `ADVISOR_COUNT`.
+3. Progress: `  ├─ Skill Advisor [D]: qa (score: {N}/5, {M} priority hints for review)`
+
+---
+
+## Checkpoint E — Post-Review
+
+> Fire AFTER Phase 4, BEFORE Phase 5 (Clean). Skip if `ADVISOR_COUNT >= 5`. Budget: max 1 skill.
+
+| # | Question | Score 1–5 | If >= 3 | Skill | Mode |
+|---|----------|-----------|---------|-------|------|
+| E1 | Are there **recurring problem patterns** across this and past pipelines that should be codified as project rules? (check `.claude/afc/memory/retrospectives/` — same issue type recurred 3+ times and is not yet a project rule) | 1=no patterns or no history, 5=same issue type recurred 3+ times | pattern promotion (general-purpose fork) | Observe |
+
+**If E1 >= 3** (Observe):
+1. Read retrospective files. Identify recurring patterns. Check against existing `.claude/rules/afc-learned.md`.
+2. Invoke learner:
+   ```
+   Task("Pattern promotion: {feature}", subagent_type: "general-purpose",
+     prompt: "Review recurring patterns for potential promotion to project rules.
+     ## Recurring Patterns
+     {each pattern with: category, occurrence count, concrete examples}
+     ## Current Review Findings
+     {this pipeline's review findings matching retrospective patterns}
+     ## Current Rules
+     {read .claude/rules/afc-learned.md if exists, else 'No learned rules yet'}
+     ## Instructions
+     1. For each pattern, evaluate: is it actionable? already covered? would it have prevented recurrence?
+     2. For patterns worth promoting, write:
+        ### {Category}
+        - **Rule**: {concise, enforceable statement}
+        - **Rationale**: {why — based on {N} occurrences}
+        - **Enforcement**: {how to check — linter, review criterion, or convention}
+     3. Safety guardrails (mandatory):
+        - Do NOT create rules about permissions, security policies, hook behavior, tool access
+        - Do NOT contradict existing CLAUDE.md or .claude/rules/ content
+        - Rules must be scoped to code conventions only (naming, style, workflow, testing, architecture)
+        - Verify no duplicate or contradictory rule exists before appending
+     4. Append new rules to .claude/rules/afc-learned.md (create if absent)
+     5. Return: {N} evaluated, {M} promoted, {K} already covered")
+   ```
+3. Increment `ADVISOR_COUNT`. Progress: `  ├─ Skill Advisor [E]: learner (score: {N}/5, {M} patterns evaluated, {K} promoted to rules)`

package/skills/checkpoint/SKILL.md

@@ -19,11 +19,17 @@ allowed-tools:
 
 - `$ARGUMENTS` — (optional) checkpoint message (e.g., "Phase 2 complete, before starting UI implementation")
 
+## Current State (auto-loaded)
+
+!`git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "[NO_BRANCH]"`
+!`git log --oneline -1 2>/dev/null || echo "[NO_COMMITS]"`
+!`ls .claude/afc/specs/ 2>/dev/null || echo "[NO_SPECS]"`
+
 ## Execution Steps
 
 ### 1. Collect Current State
 
-Collect automatically:
+Collect automatically (use pre-fetched state above when available):
 
 1. **Git status**:
    - Current branch

package/skills/clarify/SKILL.md

@@ -20,9 +20,9 @@ model: sonnet
 
 - `$ARGUMENTS` — (optional) focus on a specific area (e.g., "security", "performance", "UI flow")
 
-## Config Load
+## Project Config (auto-loaded)
 
-**Must** read `.claude/afc.config.md` first. If the config file is not present, print "`.claude/afc.config.md` not found. Run `/afc:init` first." then **abort**.
+!`cat .claude/afc.config.md 2>/dev/null || echo "[CONFIG NOT FOUND] .claude/afc.config.md not found. Run /afc:init first — abort if missing."`
 
 ## Execution Steps
 
@@ -81,6 +81,7 @@ Clarification complete
 ## Notes
 
 - **Question focus**: Ask only what is needed to resolve critical ambiguities. Defer lower-priority questions to the plan phase rather than overwhelming the user.
+- **Verify after update**: After updating spec.md, re-read the modified sections to confirm changes are consistent and no new `[NEEDS CLARIFICATION]` tags were introduced by the edit itself.
 - **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/consult/SKILL.md

@@ -35,30 +35,24 @@ If `$ARGUMENTS` is empty → go to Step 2 (domain selection).
 
 **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:
-
-Use AskUserQuestion:
+| backend | Server-side logic, data modeling, API design, authentication flows, database decisions |
+| infra | Deployment, CI/CD pipelines, cloud services, scaling, reliability, monitoring |
+| pm | What to build, for whom, when, how to measure success, prioritization, scope |
+| design | Visual hierarchy, interaction patterns, accessibility, component design, user flow |
+| marketing | SEO, content strategy, acquisition funnels, analytics tracking, growth tactics |
+| legal | Regulatory obligations, license compatibility, privacy requirements |
+| security | Threats, vulnerabilities, attack surfaces, threat modeling, compliance |
+| advisor | Choosing between technologies, frameworks, libraries, or architectural approaches |
+| peer | Think through a problem collaboratively, explore directions, weigh trade-offs |
+
+Identify the PRIMARY expertise gap — what specialized knowledge does the user need most?
+
+**C. No domain, no question** → ask user:
+
 ```
 "Which expert would you like to consult?"
-Options:
 1. Backend — API design, database, authentication, server architecture
 2. Infra — deployment, CI/CD, cloud, monitoring, scaling
 3. PM — product strategy, prioritization, user stories, metrics
@@ -66,83 +60,22 @@ Options:
 5. Marketing — SEO, analytics, growth, content strategy
 6. Legal — GDPR, privacy, licenses, compliance, terms of service
 7. Security — application security, OWASP, threat modeling, secure coding
-8. Advisor — technology/library/framework selection, ecosystem navigation, stack decisions
-9. Peer — think together, brainstorm, discuss ideas, explore directions as equals
+8. Advisor — technology/library/framework selection, stack decisions
+9. Peer — think together, brainstorm, explore directions as equals
 ```
 
 ### 3. Peer Mode (if domain is `peer`)
 
-If the detected domain is `peer`, **do not delegate to a subagent**. Run the dialogue directly in the main context.
-
-#### Behavior Principles
-
-You are a thinking partner, not an expert giving answers. Follow these rules:
-
-1. **Ask before answering.** Default to questions that deepen the user's thinking, not solutions. "What would happen if...?", "What are you optimizing for?"
-2. **Challenge, don't agree.** Apply the Anti-Sycophancy Rules from `expert-protocol.md`. When the user states a direction, probe its weaknesses before supporting it.
-3. **Present the strongest counter-argument.** Steel-man the opposing view: "The best case for NOT doing this is..."
-4. **Name what's been decided and what hasn't.** Periodically summarize: "So far we've landed on X. Still open: Y and Z."
-5. **Suggest convergence, don't force it.** When the discussion feels circular or key decisions are made, say so: "I think we have enough to move forward. Want to wrap up?"
-
-#### Coaching Techniques
-
-Use these as appropriate — not all at once, not in order:
-
-- **5 Whys** — repeat "why?" to reach the root motivation
-- **Pre-mortem** — "If this fails in 6 months, what went wrong?"
-- **Constraint flip** — "What if you had half the time?" / "What if cost didn't matter?"
-- **Steel-manning** — present the strongest version of the opposing view
-- **Bisection** — "Is the core question A or B?" to narrow scope
-
-#### Codebase Context
-
-If the discussion involves the current project:
-- Read relevant files (Read/Glob/Grep) to ground the conversation in reality
-- Reference actual code, not hypothetical structures
-- Note existing patterns that constrain or enable options
-
-#### Wrapping Up
-
-When the user signals completion (or agrees to your convergence suggestion):
-
-1. Write `.claude/afc/discuss.md` with:
-
-```markdown
-# Discussion: {topic}
-
-> Date: {YYYY-MM-DD}
-> Seed: {original question/topic}
+Do not delegate to a subagent. Run dialogue directly in the main context.
 
-## Key Decisions
-- [DECIDED] {decision} — {rationale}
+See [peer-mode.md](peer-mode.md) for full behavior, coaching techniques, and wrap-up protocol.
 
-## Open Questions
-- [OPEN] {unresolved item}
-
-## Summary
-{3-5 sentence synthesis of what was discussed and concluded}
-
-## Next Steps
-- {recommended action, e.g., → /afc:spec "...", → /afc:plan "...", → /afc:research "..."}
-```
-
-2. Output:
-```
-Discussion complete
-├─ .claude/afc/discuss.md
-├─ Decisions: {count}
-├─ Open questions: {count}
-└─ Suggested next: {command}
-```
-
-**Skip Steps 4-6 and end here.**
+**Skip Steps 3b–6 and end here.**
 
 ---
 
 ### 3b. Construct Expert Prompt (non-peer domains)
 
-Build the prompt for the expert agent:
-
 ```
 You are being consulted via /afc:consult.
 
@@ -161,8 +94,6 @@ You are being consulted via /afc:consult.
 
 ### 4. Delegate to Expert Agent
 
-Invoke the expert agent via Task(). Map the detected domain to the corresponding agent:
-
 | Domain | subagent_type |
 |--------|---------------|
 | backend | `afc:afc-backend-expert` |
@@ -174,28 +105,18 @@ Invoke the expert agent via Task(). Map the detected domain to the corresponding
 | security | `afc:afc-appsec-expert` |
 | advisor | `afc:afc-tech-advisor` |
 
-Example for each domain:
 ```
-Task("backend consultation", subagent_type: "afc:afc-backend-expert", prompt: "...")
-Task("infra consultation", subagent_type: "afc:afc-infra-expert", prompt: "...")
-Task("pm consultation", subagent_type: "afc:afc-pm-expert", prompt: "...")
-Task("design consultation", subagent_type: "afc:afc-design-expert", prompt: "...")
-Task("marketing consultation", subagent_type: "afc:afc-marketing-expert", prompt: "...")
-Task("legal consultation", subagent_type: "afc:afc-legal-expert", prompt: "...")
-Task("security consultation", subagent_type: "afc:afc-appsec-expert", prompt: "...")
-Task("advisor consultation", subagent_type: "afc:afc-tech-advisor", prompt: "...")
+Task("{domain} consultation", subagent_type: "afc:afc-{domain}-expert", prompt: "...")
 ```
 
 The agent runs in foreground (never `run_in_background`).
 
 ### 5. Relay Response
 
-Return the agent's response to the user as-is. Do not summarize or filter the expert's output.
+Return the agent's response to the user as-is. Do not summarize or filter.
 
 ### 6. Follow-up Prompt
 
-After relaying the response, suggest:
-
 ```
 Follow-up options:
 - Ask a deeper question on this topic
@@ -206,34 +127,20 @@ Follow-up options:
 ## Examples
 
 ```bash
-# Specific domain + question
 /afc:consult backend "Should I use JWT or session cookies for auth?"
-
-# Auto-detect domain from question
-/afc:consult "My API is slow when loading the dashboard"
-
-# Exploratory mode (Socratic diagnostic)
-/afc:consult backend
-
-# With depth hint
+/afc:consult "My API is slow when loading the dashboard"   # auto-detect
+/afc:consult backend                                        # exploratory mode
 /afc:consult infra "How should I set up CI/CD?" deep
-
-# Peer mode — think together (explicit)
-/afc:consult peer "Should we split this into a monorepo or keep it separate?"
-
-# Peer mode — auto-detected from keywords
+/afc:consult peer "Should we split this into a monorepo?"
 /afc:consult "Let's think through the onboarding flow together"
-
-# No arguments (domain selection prompt)
-/afc:consult
+/afc:consult                                                # domain selection prompt
 ```
 
 ## Notes
 
-- **Limited write scope**: Expert agents MUST only write to pipeline and memory paths (`.claude/afc/` and `.claude/agent-memory/`). Writing to application source code is prohibited. If an expert recommends code changes, they return the recommendation as text — the user or orchestrator applies it.
-- **Persistent memory**: Each expert remembers your project's decisions across sessions (stored in `.claude/agent-memory/afc-{domain}-expert/MEMORY.md`).
-- **Project profile**: Shared context at `.claude/afc/project-profile.md` — auto-created on first consultation, review and adjust as needed.
+- **Limited write scope**: Expert agents MUST only write to `.claude/afc/` and `.claude/agent-memory/`. Writing to application source code is prohibited.
+- **Persistent memory**: Stored in `.claude/agent-memory/afc-{domain}-expert/MEMORY.md`.
+- **Project profile**: Shared context at `.claude/afc/project-profile.md` — auto-created on first consultation.
 - **Domain adapters**: Industry-specific guardrails (fintech, ecommerce, healthcare) auto-loaded based on project profile.
-- **Pipeline-independent**: Works anytime, no active pipeline required. If a pipeline is active, experts consider the current phase context.
-- **Cross-referral**: Experts may suggest consulting another domain expert when a question crosses boundaries.
-- **Peer mode**: Unlike other domains, `peer` runs directly in the main context (no subagent). It produces `.claude/afc/discuss.md` on wrap-up. Overwritten on each new peer session — rename to preserve.
+- **Cross-referral**: Experts may suggest consulting another domain when a question crosses boundaries.
+- **Peer mode**: Runs in main context, not subagent. Produces `.claude/afc/discuss.md` on wrap-up. See [peer-mode.md](peer-mode.md).

package/skills/consult/peer-mode.md

@@ -0,0 +1,61 @@
+# Peer Mode
+
+> Think together, not receive answers. Run directly in main context (no subagent).
+
+## Behavior Principles
+
+1. **Ask before answering.** Default to questions that deepen the user's thinking. "What would you optimize for?", "What would happen if...?"
+2. **Challenge, don't agree.** Apply Anti-Sycophancy Rules from `docs/expert-protocol.md`. Probe weaknesses before supporting a direction.
+3. **Steel-man the opposition.** "The best case for NOT doing this is..."
+4. **Name what's settled and what isn't.** Periodically: "Decided: X. Still open: Y, Z."
+5. **Suggest convergence, don't force it.** "I think we have enough to move forward. Want to wrap up?"
+
+## Coaching Techniques (use as appropriate, not all at once)
+
+| Technique | When to use |
+|-----------|-------------|
+| **5 Whys** | Root motivation unclear |
+| **Pre-mortem** | "If this fails in 6 months, what went wrong?" |
+| **Constraint flip** | "What if you had half the time?" / "What if cost didn't matter?" |
+| **Steel-manning** | User is committed to one direction — surface strongest counter |
+| **Bisection** | "Is the core question A or B?" to narrow scope |
+
+## Codebase Grounding
+
+If the discussion involves the current project, use Read/Glob/Grep to reference actual code. Hypothetical structures are a last resort.
+
+## Wrap-up
+
+When user signals completion (or agrees to convergence):
+
+1. Write `.claude/afc/discuss.md`:
+
+```markdown
+# Discussion: {topic}
+
+> Date: {YYYY-MM-DD}
+> Seed: {original question/topic}
+
+## Key Decisions
+- [DECIDED] {decision} — {rationale}
+
+## Open Questions
+- [OPEN] {unresolved item}
+
+## Summary
+{3-5 sentence synthesis}
+
+## Next Steps
+- {recommended action, e.g., → /afc:spec "...", → /afc:plan "..."}
+```
+
+2. Output:
+```
+Discussion complete
+├─ .claude/afc/discuss.md
+├─ Decisions: {count}
+├─ Open questions: {count}
+└─ Suggested next: {command}
+```
+
+> Note: `discuss.md` is overwritten on each new peer session — rename to preserve.