refactor(skills): consolidate 28 → 24 unified patterns (pre-v1.0.0)

CLAUDE.md

@@ -35,7 +35,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 28 skills (single source of truth)
+├── shared/skills/          # 24 skills (single source of truth)
 ├── shared/agents/          # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 8 self-contained plugins
 ├── docs/reference/         # Detailed reference documentation

CONTRIBUTING.md

@@ -24,7 +24,7 @@ After setup, DevFlow commands (`/review`, `/implement`, etc.) are available in C
 
 ```
 devflow/
-├── shared/skills/       # 28 skills (single source of truth)
+├── shared/skills/       # 24 skills (single source of truth)
 ├── shared/agents/       # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/   # 10 self-contained plugins
 ├── scripts/hooks/       # Working Memory hooks

README.md

@@ -109,10 +109,9 @@ The `devflow-core-skills` plugin provides quality enforcement skills that activa
 
 | Skill | Triggers When |
 |-------|---------------|
-| `commit` | Staging files, creating commits |
-| `pull-request` | Creating PRs |
-| `test-design` | Writing or modifying tests |
-| `code-smell` | Implementing features |
+| `core-patterns` | Implementing business logic, error handling |
+| `git-workflow` | Staging files, creating commits, PRs |
+| `test-patterns` | Writing or modifying tests |
 | `input-validation` | Creating API endpoints |
 | `typescript` | Working in TypeScript codebases |
 | `react` | Working with React components |

docs/reference/file-organization.md

@@ -9,7 +9,7 @@ devflow/
 ├── .claude-plugin/                   # Marketplace registry (repo root)
 │   └── marketplace.json
 ├── shared/
-│   ├── skills/                       # SINGLE SOURCE OF TRUTH (28 skills)
+│   ├── skills/                       # SINGLE SOURCE OF TRUTH (24 skills)
 │   │   ├── commit/
 │   │   │   ├── SKILL.md
 │   │   │   └── references/
@@ -74,7 +74,7 @@ devflow-{name}/
   "description": "Complete task implementation workflow",
   "version": "0.9.0",
   "agents": ["git", "coder", "synthesizer"],
-  "skills": ["codebase-navigation", "implementation-patterns", "self-review"]
+  "skills": ["implementation-patterns", "self-review"]
 }
 ```
 

docs/reference/skills-architecture.md

@@ -12,19 +12,19 @@ Shared patterns used by multiple agents.
 
 | Skill | Purpose | Used By |
 |-------|---------|---------|
-| `core-patterns` | Engineering patterns (Result types, DI, immutability, pure functions) | Coder, Reviewer |
-| `review-methodology` | 6-step review process, 3-category issue classification | Reviewer |
+| `core-patterns` | Engineering patterns (Result types, DI, immutability, workaround labeling) | Coder, Scrutinizer, Resolver, Shepherd |
+| `review-methodology` | 6-step review process, 3-category issue classification | Reviewer, Synthesizer |
 | `self-review` | 9-pillar self-review framework | Scrutinizer |
 | `docs-framework` | Documentation conventions (.docs/ structure, naming, templates) | Synthesizer |
-| `git-safety` | Git operations, lock handling, commit conventions | Coder, Git |
+| `git-safety` | Git operations, lock handling, sequential ops | Coder, Git, Resolver |
+| `git-workflow` | Atomic commits, message format, PR descriptions, size assessment | Coder, Git, Resolver |
 | `github-patterns` | GitHub API patterns (rate limiting, PR comments, issues, releases) | Git |
-| `implementation-patterns` | CRUD, API endpoints, events, config, logging | Coder |
-| `codebase-navigation` | Exploration, entry points, data flow tracing, pattern discovery | Coder |
+| `implementation-patterns` | CRUD, API endpoints, events, config, logging | Coder, Resolver |
 | `agent-teams` | Agent Teams patterns for peer-to-peer collaboration, debate, consensus | /review, /implement, /debug |
 
 ### Tier 1b: Pattern Skills
 
-Domain expertise for Reviewer agent focus areas.
+Domain expertise for Reviewer agent focus areas. Loaded dynamically based on review focus parameter.
 
 | Skill | Purpose | Reviewer Focus |
 |-------|---------|----------------|
@@ -33,47 +33,52 @@ Domain expertise for Reviewer agent focus areas.
 | `performance-patterns` | Algorithms, N+1, memory, I/O, caching | `performance` |
 | `complexity-patterns` | Cyclomatic complexity, readability, maintainability | `complexity` |
 | `consistency-patterns` | Pattern violations, simplification, truncation | `consistency` |
-| `tests-patterns` | Coverage, quality, brittle tests, mocking | `tests` |
+| `test-patterns` | Coverage, quality, brittle tests, mocking, test design | `tests` |
 | `database-patterns` | Schema, queries, migrations, indexes | `database` |
 | `documentation-patterns` | Docs quality, alignment, code-comment drift | `documentation` |
 | `dependencies-patterns` | CVEs, versions, licenses, supply chain | `dependencies` |
 | `regression-patterns` | Lost functionality, broken behavior, migrations | `regression` |
 
 ### Tier 2: Specialized Skills
 
-User-facing, auto-activate based on context.
+Listed in Claude Code's skill catalog. May auto-invoke based on description matching, but primary activation is through agent frontmatter references.
 
-| Skill | Purpose | Auto-Triggers When |
-|-------|---------|---------------------|
-| `test-design` | Test quality enforcement | Tests written or modified |
-| `code-smell` | Anti-pattern detection | Features implemented, code reviewed |
-| `commit` | Atomic commit patterns, message format | Staging files, creating commits |
-| `pull-request` | PR quality, size assessment | Creating PRs |
-| `input-validation` | Boundary validation enforcement | API endpoints created, external data handled |
+| Skill | Purpose | Agent Refs |
+|-------|---------|------------|
+| `input-validation` | Boundary validation enforcement | Coder |
 
 ### Tier 3: Domain-Specific Skills
 
-Language and framework patterns.
+Language and framework patterns. Referenced by agents via frontmatter and conditionally activated by Reviewer.
 
 | Skill | Purpose | Used When |
 |-------|---------|-----------|
 | `typescript` | Type safety, generics, utility types, type guards | TypeScript codebases |
 | `react` | Components, hooks, state management, performance | React codebases |
+| `accessibility` | Keyboard, ARIA, focus, color contrast | Frontend codebases |
+| `frontend-design` | Typography, color, spacing, visual design | Frontend codebases |
 
-## How Agents Use Skills
+## How Skills Activate
 
-Agents declare skills in their frontmatter to automatically load shared knowledge:
+Skills activate through two guaranteed mechanisms:
+
+1. **Agent frontmatter `skills:` field** — When an agent runs, all skills listed in its frontmatter are loaded into context. This is the primary activation path.
+2. **Reviewer dynamic read** — The Reviewer agent reads the pattern skill file for its assigned focus area from a lookup table (e.g., `focus=tests` → `test-patterns/SKILL.md`).
+
+Skills with `user-invocable: false` also appear in Claude Code's skill catalog with their description. Claude MAY auto-invoke them based on description matching, but this is not guaranteed and should not be relied upon as the sole activation path.
+
+The `activation: file-patterns` frontmatter is metadata for documentation purposes. Claude Code does not currently use glob patterns to trigger skills.
+
+### Example: Agent Frontmatter
 
 ```yaml
 ---
-name: Reviewer
-description: Universal code review agent with parameterized focus
-model: inherit
-skills: review-methodology, security-patterns, architecture-patterns, ...
+name: Coder
+skills: core-patterns, git-safety, implementation-patterns, git-workflow, ...
 ---
 ```
 
-The unified `Reviewer` agent loads ALL pattern skills and applies the relevant one based on the focus area specified in its invocation prompt.
+All listed skills are loaded when the Coder agent is spawned.
 
 ## Skill File Template
 
@@ -179,9 +184,9 @@ activation:
 | `typescript` | `**/*.ts`, `**/*.tsx` | `node_modules/**`, `**/*.d.ts` |
 | `accessibility` | `**/*.tsx`, `**/*.jsx`, `**/*.css` | `node_modules/**` |
 | `frontend-design` | `**/*.tsx`, `**/*.jsx`, `**/*.css`, `**/*.scss` | `node_modules/**` |
-| `test-design` | `**/*.test.*`, `**/*.spec.*`, `**/test/**` | `node_modules/**` |
+| `test-patterns` | `**/*.test.*`, `**/*.spec.*`, `**/test/**` | `node_modules/**` |
 
-**Note:** Glob patterns are currently metadata hints for future Claude Code support of conditional skill loading.
+**Note:** Glob patterns are metadata hints for documentation. Claude Code does not currently read glob patterns to trigger skills — activation happens through agent frontmatter and Reviewer dynamic read (see "How Skills Activate" above).
 
 ## Skill vs Command Decision
 

plugins/devflow-core-skills/.claude-plugin/plugin.json

@@ -13,17 +13,15 @@
   "agents": [],
   "skills": [
     "accessibility",
-    "code-smell",
-    "commit",
     "core-patterns",
     "docs-framework",
     "frontend-design",
     "git-safety",
+    "git-workflow",
     "github-patterns",
     "input-validation",
-    "pull-request",
     "react",
-    "test-design",
+    "test-patterns",
     "typescript"
   ]
 }

plugins/devflow-core-skills/README.md

@@ -16,10 +16,9 @@ npx devflow-kit init --plugin=core-skills
 
 | Skill | Auto-Triggers When | What It Enforces |
 |-------|-------------------|------------------|
-| `commit` | Staging files, creating commits | Atomic commits, message format, safety scanning |
-| `pull-request` | Creating PRs, generating descriptions | PR quality, size assessment, breaking change detection |
-| `test-design` | Tests written or modified | Test quality, setup complexity, behavior testing |
-| `code-smell` | Features implemented, code reviewed | Anti-patterns, fake solutions, magic values |
+| `core-patterns` | Business logic, error handling | Result types, DI, immutability, workaround labeling |
+| `git-workflow` | Staging files, creating commits, PRs | Atomic commits, message format, PR descriptions |
+| `test-patterns` | Tests written or modified | Test quality, setup complexity, behavior testing, coverage |
 | `input-validation` | API endpoints, external data handling | Boundary validation, parse-don't-validate |
 | `typescript` | TypeScript codebases | Type safety, generics, utility types |
 | `react` | React codebases | Components, hooks, state management |
@@ -34,10 +33,9 @@ Each skill enforces a non-negotiable principle:
 
 | Skill | Iron Law |
 |-------|----------|
-| `commit` | ATOMIC COMMITS OR NO COMMITS |
-| `pull-request` | HONEST DESCRIPTIONS OR NO PR |
-| `test-design` | COMPLEX TESTS INDICATE BAD DESIGN |
-| `code-smell` | NO FAKE SOLUTIONS |
+| `core-patterns` | NEVER THROW IN BUSINESS LOGIC |
+| `git-workflow` | ATOMIC COMMITS WITH HONEST DESCRIPTIONS |
+| `test-patterns` | TESTS VALIDATE BEHAVIOR, NOT IMPLEMENTATION |
 | `input-validation` | ALL EXTERNAL DATA IS HOSTILE |
 | `typescript` | UNKNOWN OVER ANY |
 | `react` | COMPOSITION OVER PROPS |

plugins/devflow-implement/.claude-plugin/plugin.json

@@ -14,7 +14,6 @@
   "skills": [
     "accessibility",
     "agent-teams",
-    "codebase-navigation",
     "frontend-design",
     "implementation-patterns",
     "self-review"

plugins/devflow-implement/README.md

@@ -46,19 +46,17 @@ npx devflow-kit init --plugin=implement
 - `shepherd` - Alignment validation
 - `validator` - Build/test validation
 
-### Skills (12)
-- `core-patterns` - Result types, DI, immutability
+### Skills (10)
+- `core-patterns` - Result types, DI, immutability, workaround labeling
 - `git-safety` - Safe git operations
-- `commit` - Atomic commit patterns
-- `pull-request` - PR quality enforcement
+- `git-workflow` - Atomic commits, PR descriptions
 - `implementation-patterns` - CRUD, API, events
-- `codebase-navigation` - Pattern discovery
-- `test-design` - Test quality
-- `code-smell` - Anti-pattern detection
+- `test-patterns` - Test quality, coverage
 - `input-validation` - Boundary validation
 - `self-review` - 9-pillar framework
 - `typescript` - TypeScript patterns
 - `react` - React patterns
+- `accessibility` - Keyboard, ARIA, focus management
 
 ## Output
 

plugins/devflow-implement/agents/git.md

@@ -2,7 +2,7 @@
 name: Git
 description: Unified agent for all git/GitHub operations - issues, PR comments, tech debt, releases
 model: haiku
-skills: github-patterns, git-safety, commit, pull-request
+skills: github-patterns, git-safety, git-workflow
 ---
 
 # Git Agent
@@ -37,9 +37,9 @@ Pre-flight checks and fixes for `/review`. Ensures branch is ready for code revi
 
 **Process:**
 1. Verify on feature branch (not main/master/develop) - error if not
-2. Check for uncommitted changes - if any, create atomic commit using `commit` patterns
+2. Check for uncommitted changes - if any, create atomic commit using `git-workflow` patterns
 3. Check if branch pushed to remote - if not, push with `-u` flag
-4. Check if PR exists - if not, create PR using `pull-request` patterns
+4. Check if PR exists - if not, create PR using `git-workflow` patterns
 5. Get base branch from PR
 6. Derive branch-slug (replace `/` with `-`)
 

plugins/devflow-implement/agents/synthesizer.md

@@ -2,7 +2,7 @@
 name: Synthesizer
 description: Combines outputs from multiple agents into actionable summaries (modes: exploration, planning, review)
 model: haiku
-skills: review-methodology
+skills: review-methodology, docs-framework
 ---
 
 # Synthesizer Agent

plugins/devflow-implement/agents/validator.md

@@ -2,7 +2,7 @@
 name: Validator
 description: Dedicated agent for running validation commands (build, typecheck, lint, test). Reports pass/fail with structured failure details - never fixes.
 model: haiku
-skills: test-design
+skills: test-patterns
 ---
 
 # Validator Agent

plugins/devflow-implement/commands/implement-teams.md

@@ -69,7 +69,7 @@ Spawn exploration teammates with self-contained prompts:
 - Name: "architecture-explorer"
   Prompt: |
     You are exploring a codebase for task: {task description}
-    1. Read your skill: `Read ~/.claude/skills/codebase-navigation/SKILL.md`
+    1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md`
     2. Skimmer context (files/patterns already identified):
        {skimmer output}
     3. Your deliverable: Find similar implementations, established patterns,
@@ -81,7 +81,7 @@ Spawn exploration teammates with self-contained prompts:
 - Name: "integration-explorer"
   Prompt: |
     You are exploring a codebase for task: {task description}
-    1. Read your skill: `Read ~/.claude/skills/codebase-navigation/SKILL.md`
+    1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md`
     2. Skimmer context (files/patterns already identified):
        {skimmer output}
     3. Your deliverable: Find entry points, services, database models,
@@ -93,7 +93,7 @@ Spawn exploration teammates with self-contained prompts:
 - Name: "reusable-code-explorer"
   Prompt: |
     You are exploring a codebase for task: {task description}
-    1. Read your skill: `Read ~/.claude/skills/codebase-navigation/SKILL.md`
+    1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md`
     2. Skimmer context (files/patterns already identified):
        {skimmer output}
     3. Your deliverable: Find utilities, helpers, validation patterns,
@@ -105,7 +105,7 @@ Spawn exploration teammates with self-contained prompts:
 - Name: "edge-case-explorer"
   Prompt: |
     You are exploring a codebase for task: {task description}
-    1. Read your skill: `Read ~/.claude/skills/codebase-navigation/SKILL.md`
+    1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md`
     2. Skimmer context (files/patterns already identified):
        {skimmer output}
     3. Your deliverable: Find error scenarios, race conditions, permission
@@ -179,7 +179,7 @@ Spawn planning teammates with self-contained prompts:
 - Name: "testing-planner"
   Prompt: |
     You are planning the test strategy for task: {task description}
-    1. Read your skill: `Read ~/.claude/skills/test-design/SKILL.md`
+    1. Read your skill: `Read ~/.claude/skills/test-patterns/SKILL.md`
     2. Exploration synthesis (what we know about the codebase):
        {synthesis output from Phase 3}
     3. Your deliverable: Test strategy — unit tests, integration tests,