@dzhechkov/p-replicator 1.0.0

package/templates/.claude/skills/knowledge-extractor/modules/01-agent-review.md

@@ -0,0 +1,192 @@
+# Phase 1: Agent Review
+
+AI-assisted project scanning using a swarm of 5 parallel extraction agents.
+
+## Goal
+
+Find all extractable knowledge in the project — patterns, commands, rules, templates,
+snippets, skills, and hooks that could be reused in other projects.
+
+## Input
+
+- Project codebase (current working directory)
+- `TOOLKIT_HARVEST.md` markers (if exists in project root)
+- User context about what was valuable (if provided)
+
+## Swarm of Extraction Agents
+
+Launch 5 parallel agents via Task tool. Each agent independently scans the codebase
+from its perspective.
+
+### Agent: extractor-patterns
+
+**Scope:** Architecture and code patterns
+
+**Scan for:**
+- Middleware implementations (rate limiting, auth, logging, caching)
+- Error handling patterns (retries, circuit breakers, fallbacks)
+- Data access patterns (repository, DAO, query builders)
+- Communication patterns (pub/sub, event sourcing, CQRS)
+- Configuration patterns (env loading, feature flags, multi-env)
+- Testing patterns (fixtures, factories, custom matchers)
+
+**How to scan:**
+1. Look at directory structure for architectural patterns
+2. Scan for abstract/generic implementations (not domain-specific)
+3. Check for reusable middleware or interceptors
+4. Look for utility modules that solve common problems
+5. Check `TOOLKIT_HARVEST.md` → Patterns section
+
+**Output per finding:**
+```markdown
+- **Name:** [Pattern Name]
+- **File:** [path/to/file.ext:line]
+- **Description:** [1 sentence]
+- **Reusability:** HIGH | MEDIUM | LOW
+- **Why reusable:** [reason]
+```
+
+### Agent: extractor-commands
+
+**Scope:** Scripts, CLI utilities, slash commands
+
+**Scan for:**
+- Shell scripts in `scripts/`, `bin/`, `tools/`
+- Package.json scripts / Makefile targets / Taskfile tasks
+- Database migration commands
+- Code generation utilities
+- Dev environment setup scripts
+- CI/CD pipeline steps that could be local commands
+- Existing `.claude/commands/` that are generalizable
+
+**How to scan:**
+1. List all executable scripts
+2. Check package.json / Makefile / Taskfile for useful targets
+3. Check `.claude/commands/` for project-specific commands worth generalizing
+4. Check `TOOLKIT_HARVEST.md` → Commands section
+
+**Output per finding:**
+```markdown
+- **Name:** [Command Name]
+- **File:** [path]
+- **What it does:** [1 sentence]
+- **Generalizability:** HIGH | MEDIUM | LOW
+- **Dependencies:** [external tools needed]
+```
+
+### Agent: extractor-rules
+
+**Scope:** Constraints, workarounds, lessons learned
+
+**Scan for:**
+- Comments with `TODO`, `HACK`, `WORKAROUND`, `NOTE`, `FIXME`
+- Known issues documented in README or docs
+- Edge cases in tests (especially ones that were hard to find)
+- Library-specific quirks discovered during development
+- Performance constraints discovered empirically
+- Security constraints that weren't obvious
+- Claude Code limitations (things that don't work well with AI)
+
+**How to scan:**
+1. Grep for `TODO|HACK|WORKAROUND|NOTE|FIXME|XXX|BUG`
+2. Check README/docs for "gotchas" or "known issues"
+3. Look at test names for edge case descriptions
+4. Check git commit messages for "fix:" — these often encode lessons
+5. Check `TOOLKIT_HARVEST.md` → Lessons/Rules section
+
+**Output per finding:**
+```markdown
+- **Rule:** [Don't do X because Y]
+- **Source:** [file:line or commit:hash]
+- **Type:** Constraint | Workaround | Lesson | Limitation
+- **Scope:** Universal | Language-specific | Framework-specific
+- **Expiry:** Permanent | Check in [timeframe]
+```
+
+### Agent: extractor-templates
+
+**Scope:** File structures, configs, project scaffolds
+
+**Scan for:**
+- Dockerfile / docker-compose.yml patterns
+- CI/CD configuration (.github/workflows, .gitlab-ci.yml)
+- Linter/formatter configs (.eslintrc, .prettierrc, rustfmt.toml)
+- Project structure conventions
+- Testing configuration
+- Monitoring/logging setup
+- Environment configuration templates
+
+**How to scan:**
+1. List all config/dot files
+2. Identify which configs are project-specific vs. generalizable
+3. Check for well-structured Dockerfiles worth reusing
+4. Check CI/CD configs for reusable job definitions
+5. Check `TOOLKIT_HARVEST.md` → Templates section
+
+**Output per finding:**
+```markdown
+- **Name:** [Template Name]
+- **File:** [path]
+- **What it templates:** [1 sentence]
+- **Parameterizable:** YES (what params) | NO (why)
+- **Tech stack:** [language/framework]
+```
+
+### Agent: extractor-snippets
+
+**Scope:** Small, ready-to-use code fragments
+
+**Scan for:**
+- Utility functions in `utils/`, `helpers/`, `lib/`, `common/`
+- One-liners that solve common problems
+- Type definitions / interfaces that are universal
+- Error handler implementations
+- Validation functions
+- Date/time helpers
+- String manipulation utilities
+- HTTP client wrappers
+
+**How to scan:**
+1. Scan utility directories
+2. Look for small (<50 lines) functions with no domain dependencies
+3. Check for functions used across multiple modules (sign of universality)
+4. Check `TOOLKIT_HARVEST.md` → Snippets section
+
+**Output per finding:**
+```markdown
+- **Name:** [Snippet Name]
+- **File:** [path:line]
+- **Language:** [lang]
+- **Lines:** [count]
+- **Dependencies:** None | [list]
+- **What it does:** [1 sentence]
+```
+
+## Merging Strategy
+
+After all 5 agents complete:
+
+1. **Deduplicate** — same finding reported by multiple agents → keep richest description
+2. **Cross-reference** — if a pattern is also a template, note both categories
+3. **Sort by confidence** — HIGH reusability first
+4. **Count** — total findings, per-category breakdown
+5. **Include TOOLKIT_HARVEST.md markers** — merge manual markers with auto-discovered
+
+## Output: Raw Findings List
+
+```markdown
+## Raw Findings
+
+### Summary
+- Total candidates: [N]
+- From agents: [M] (unique after dedup)
+- From TOOLKIT_HARVEST.md markers: [K]
+- By category: Skills [X], Commands [Y], Patterns [Z], Rules [A], Templates [B], Snippets [C], Hooks [D]
+
+### Findings Table
+
+| # | Finding | Source | Category | Reusability | Agent |
+|---|---------|--------|----------|-------------|-------|
+| 1 | [name] | [file:line] | [category] | HIGH | extractor-patterns |
+| 2 | [name] | [file:line] | [category] | MEDIUM | extractor-commands |
+```

package/templates/.claude/skills/knowledge-extractor/modules/02-classify.md

@@ -0,0 +1,122 @@
+# Phase 2: Classify
+
+Map raw findings to the 7 artifact categories and filter out non-extractables.
+
+## Goal
+
+Transform the Raw Findings List into a curated Classified Artifact List.
+Every finding must either be assigned a category or explicitly excluded with reason.
+
+## 7 Artifact Categories
+
+| # | Category | Directory | What Belongs | Example |
+|---|----------|-----------|-------------|---------|
+| 1 | **Skills** | `skills/` | New or improved SKILL.md techniques | Better API integration technique |
+| 2 | **Commands** | `commands/` | Slash commands for Claude Code | `/api-endpoint` generates CRUD |
+| 3 | **Hooks** | `hooks/` | Pre-commit, post-task, CI automation | Auto-validate OpenAPI schema |
+| 4 | **Rules** | `rules/` | Constraints, limitations, "don't do X" | "Nested generics >3 levels break AI" |
+| 5 | **Templates** | `templates/` | Reusable file/project structures | Dockerfile for Node+Postgres |
+| 6 | **Patterns** | `patterns/` | Architectural approaches as docs | Event sourcing + CQRS |
+| 7 | **Snippets** | `snippets/` | Small ready code fragments (<50 lines) | Universal retry with backoff |
+
+See `references/artifact-categories.md` for detailed criteria per category.
+
+## Classification Process
+
+For each finding from Phase 1:
+
+### Step 1: Apply Exclusion Filter
+
+**Exclude if ANY of these are true:**
+
+| Exclusion Criteria | Reason |
+|-------------------|--------|
+| Domain-specific (business logic) | Won't generalize |
+| Used exactly once, unvalidated | Not proven enough |
+| Library bugfix workaround | Will expire with next lib version |
+| Contains secrets/credentials | Security risk |
+| Hardcoded business rules | Not transferable |
+| Extremely framework-specific | Too narrow scope |
+
+**Exception:** Library workarounds CAN be extracted as temporary rules
+with a review date: `## Expiry: Check after [library] v[next]`
+
+### Step 2: Determine Primary Category
+
+Use this decision tree:
+
+```
+Is it executable logic (<50 lines)?
+  → YES: Snippet
+  → NO: Continue
+
+Is it a complete workflow/process?
+  → YES: Is it a Claude Code slash command?
+    → YES: Command
+    → NO: Skill
+  → NO: Continue
+
+Is it an automation trigger?
+  → YES: Hook
+  → NO: Continue
+
+Is it a constraint or lesson?
+  → YES: Rule
+  → NO: Continue
+
+Is it a file structure or config?
+  → YES: Template
+  → NO: Continue
+
+Is it an architectural approach?
+  → YES: Pattern
+  → NO: Reconsider — may not be extractable
+```
+
+### Step 3: Assess Cross-Category
+
+Some artifacts span categories. Mark secondary categories:
+
+| Primary | Common Secondary |
+|---------|-----------------|
+| Pattern | Template (implementation scaffold) |
+| Snippet | Pattern (if part of larger pattern) |
+| Command | Hook (if automatable) |
+| Rule | Snippet (code that enforces the rule) |
+| Skill | Command (entry point for the skill) |
+
+### Step 4: Confidence Rating
+
+| Rating | Meaning | Criteria |
+|--------|---------|----------|
+| **HIGH** | Definitely extract | Universal, proven, well-tested |
+| **MEDIUM** | Likely extract | Needs some generalization |
+| **LOW** | Maybe extract | Needs significant rework, questionable reusability |
+
+## Output: Classified Artifact List
+
+```markdown
+## Classified Artifacts
+
+### ✅ Extract ([N] artifacts)
+
+| # | Artifact | Primary | Secondary | Confidence | Notes |
+|---|----------|---------|-----------|------------|-------|
+| 1 | Retry with backoff | Pattern | Snippet | HIGH | Universal HTTP retry |
+| 2 | /db-migrate | Command | - | MEDIUM | Needs param extraction |
+| 3 | Error boundary pattern | Pattern | Template | HIGH | Works with any framework |
+
+### ❌ Skip ([M] items)
+
+| # | Finding | Reason |
+|---|---------|--------|
+| 4 | Auth middleware | Domain-specific (user model tied) |
+| 5 | Stripe webhook handler | Too platform-specific |
+| 6 | Temp fix for lib bug #123 | Will expire, library-specific |
+
+### ⚠️ Uncertain ([K] items)
+
+| # | Finding | Question | Decision Needed |
+|---|---------|----------|-----------------|
+| 7 | Custom ORM wrapper | Generalizable or too specific? | User input |
+```

package/templates/.claude/skills/knowledge-extractor/modules/03-decontextualize.md

@@ -0,0 +1,156 @@
+# Phase 3: Decontextualize
+
+Transform project-specific artifacts into reusable, documented toolkit entries.
+
+## Goal
+
+Each classified artifact must be generalized so it works in ANY project,
+not just the one it was extracted from. This is the critical step that separates
+"copying code" from "building a toolkit."
+
+## The 3-Step Decontextualization
+
+### Step 1: Remove Project Specifics
+
+**Find and replace:**
+
+| Project-Specific | Generalized Replacement |
+|-----------------|----------------------|
+| Concrete service names (`auth-service`) | `{{SERVICE_NAME}}` or generic (`service`) |
+| Specific paths (`src/auth/errors.rs`) | Pattern description ("error handling module") |
+| Hardcoded configs (`port: 3000`) | Parameters (`port: {{PORT}}`) |
+| Specific DB names/tables | Generic schema references |
+| API endpoint paths (`/api/v1/users`) | `{{API_PREFIX}}/{{RESOURCE}}` |
+| Company/product names | `{{PROJECT_NAME}}` |
+| Specific env variables | Documented parameter list |
+| Concrete user models | Interface/trait with required methods |
+
+**Example transformation:**
+
+Before (project-specific):
+```rust
+// auth-service/src/middleware/rate_limit.rs
+pub fn rate_limit(config: &AuthConfig) -> RateLimiter {
+    RateLimiter::new(config.max_requests, config.window_secs)
+}
+```
+
+After (decontextualized):
+```rust
+// Pattern: Rate Limiting Middleware
+// Works with any HTTP service
+pub fn rate_limit<C: RateLimitConfig>(config: &C) -> RateLimiter {
+    RateLimiter::new(config.max_requests(), config.window_duration())
+}
+
+// Required trait for configuration
+pub trait RateLimitConfig {
+    fn max_requests(&self) -> u32;
+    fn window_duration(&self) -> Duration;
+}
+```
+
+### Step 2: Document Usage
+
+Every artifact gets documentation following `templates/artifact-card.md`:
+
+**Required sections:**
+1. **Title** — descriptive name
+2. **When to Use** — conditions where this artifact applies
+3. **When NOT to Use** — explicit anti-patterns
+4. **Prerequisites** — what must exist before using this
+5. **Implementation** — the generalized code/pattern/template
+6. **Variants** — alternative implementations for different contexts
+7. **Source** — provenance (project, date, version)
+
+**Optional sections:**
+- **Gotchas** — things that can go wrong
+- **Related Artifacts** — links to complementary artifacts
+- **Performance Notes** — benchmarks, trade-offs
+
+### Step 3: Version & Provenance
+
+Every artifact must have a maturity block:
+
+```markdown
+## Maturity: 🔴 Alpha
+## Used in: [source-project]
+## Extracted: [DATE]
+## Last updated: [DATE]
+## Changelog:
+- v1: Initial extraction from [source-project]
+```
+
+See `references/maturity-model.md` for maturity progression rules.
+
+## Quality Gate
+
+Apply to each artifact before it can proceed to Phase 4:
+
+| # | Check | Threshold | Blocking? |
+|---|-------|-----------|-----------|
+| 1 | No project-specific names | 0 remaining | YES |
+| 2 | No hardcoded paths | 0 remaining | YES |
+| 3 | "When to Use" section | Must exist | YES |
+| 4 | "When NOT to Use" section | Must exist | YES |
+| 5 | Prerequisites documented | Must exist | YES |
+| 6 | At least 1 usage variant | Recommended | NO |
+| 7 | Code compiles standalone | Must pass (code) | YES |
+| 8 | Maturity level assigned | Must exist | YES |
+| 9 | Source project recorded | Must exist | YES |
+
+**If `brutal-honesty-review` skill available:**
+
+Apply Bach-mode BS detection:
+- "Is this ACTUALLY reusable, or are we fooling ourselves?"
+- "Would this work if transplanted to a completely different project?"
+- "Is the generalization genuine or superficial (just renamed variables)?"
+
+## Decontextualization Patterns by Category
+
+### For Patterns
+- Replace concrete types with generics/traits/interfaces
+- Extract configuration into parameters
+- Document the PRINCIPLE, not just the implementation
+- Provide at least 2 language/framework variants if possible
+
+### For Commands
+- Replace project paths with `$PROJECT_ROOT` or auto-detection
+- Make tool dependencies explicit (what must be installed)
+- Add argument parsing for project-specific values
+- Document required environment variables
+
+### For Rules
+- State the UNIVERSAL principle, not the project symptom
+- Include example of what goes wrong (without project specifics)
+- Specify scope: universal vs. language-specific vs. framework-specific
+- Add expiry date for library-specific workarounds
+
+### For Templates
+- Replace all hardcoded values with `{{PLACEHOLDERS}}`
+- Document every placeholder with type and default value
+- Include comments explaining WHY each section exists
+- Test that template works with example values
+
+### For Snippets
+- Remove all import/require statements that are project-specific
+- Document required dependencies
+- Add type signatures / function documentation
+- Ensure the snippet is self-contained (<50 lines)
+
+### For Skills
+- Follow `pipeline-forge` skill anatomy (view `.claude/skills/pipeline-forge/references/skill-anatomy.md`)
+- Include SKILL.md with frontmatter
+- Add trigger patterns
+- Document input/output formats
+
+### For Hooks
+- Make the triggering event configurable
+- Document which tool/framework the hook targets
+- Include installation instructions
+- Add enable/disable mechanism
+
+## Output
+
+Each artifact is now a complete, documented, generalized entry ready for toolkit integration.
+The output is a set of files (one per artifact) following the `templates/artifact-card.md` format.

package/templates/.claude/skills/knowledge-extractor/modules/04-integrate.md

@@ -0,0 +1,178 @@
+# Phase 4: Integrate
+
+Write generalized artifacts to the toolkit and update the index.
+
+## Goal
+
+Place each artifact in its correct toolkit location, handle version conflicts,
+and produce a comprehensive Harvest Report.
+
+## Integration Process
+
+### Step 1: Determine Target Location
+
+Each artifact category has a default target:
+
+| Category | Default Target | Alternative |
+|----------|---------------|-------------|
+| Skills | `.claude/skills/[name]/SKILL.md` | External toolkit repo |
+| Commands | `.claude/commands/[name].md` | External toolkit repo |
+| Hooks | `.claude/settings.json` or `.claude/hooks/` | git hooks |
+| Rules | `.claude/rules/[name].md` | CLAUDE.md inline |
+| Templates | `templates/[name]/` or `.claude/templates/` | Standalone repo |
+| Patterns | `docs/patterns/[name].md` or `patterns/` | Knowledge base |
+| Snippets | `snippets/[lang]/[name].[ext]` or inline in docs | Gist/snippet manager |
+
+**Target selection:**
+- If integrating into current project → `.claude/` or project root
+- If integrating into external toolkit → specify toolkit path
+- If creating new repo → use pipeline-forge to scaffold
+
+### Step 2: Handle Existing Artifacts
+
+When an artifact with the same name already exists:
+
+| Scenario | Action |
+|----------|--------|
+| New artifact | Write directly |
+| Same name, different version | Merge: update version, add new variants |
+| Same name, same content | Skip (already extracted) |
+| Conflict (different approach) | Show both, ask user which to keep |
+
+**Version merge process:**
+1. Read existing artifact
+2. Compare with new extraction
+3. If new adds value → increment version, add to changelog
+4. If new is different approach → present as variant
+5. Update maturity level if warranted
+
+### Step 3: Write Artifacts
+
+For each artifact:
+
+1. Create file at target location
+2. Ensure directory exists
+3. Write using `templates/artifact-card.md` format
+4. Verify file was written successfully
+
+**Skills (special handling):**
+If artifact is a Skill, use pipeline-forge's skill anatomy:
+```
+.claude/skills/[skill-name]/
+├── SKILL.md
+├── references/    (if needed)
+└── templates/     (if needed)
+```
+
+### Step 4: Update Toolkit Index
+
+After all artifacts are written, update the toolkit index.
+
+**If CLAUDE.md is the index:**
+Add/update the toolkit section:
+
+```markdown
+## Toolkit Artifacts
+
+### Skills
+| Skill | Maturity | Description | Source |
+|-------|----------|-------------|--------|
+| [name] | 🔴/🟡/🟢 | [desc] | [project], [date] |
+
+### Patterns
+| Pattern | Maturity | Description | Source |
+|---------|----------|-------------|--------|
+| [name] | 🔴/🟡/🟢 | [desc] | [project], [date] |
+
+[... for each category with artifacts]
+
+Last harvest: [DATE]
+Total artifacts: [N]
+```
+
+**If standalone manifest:**
+Write to `.claude/toolkit-manifest.json`:
+```json
+{
+  "last_harvest": "2026-03-01",
+  "artifacts": [
+    {
+      "name": "retry-with-backoff",
+      "category": "pattern",
+      "maturity": "alpha",
+      "path": "docs/patterns/retry-with-backoff.md",
+      "source_project": "api-gateway",
+      "extracted": "2026-03-01",
+      "version": 1
+    }
+  ]
+}
+```
+
+### Step 5: Generate Harvest Report
+
+Produce a summary report using `templates/harvest-report.md`:
+
+```markdown
+# Harvest Report: [Project Name]
+Date: [DATE]
+
+## Summary
+| Metric | Value |
+|--------|-------|
+| Files scanned | [N] |
+| Candidates found | [M] |
+| Artifacts extracted | [K] |
+| Artifacts skipped | [J] |
+| New artifacts | [X] |
+| Updated artifacts | [Y] |
+
+## Extracted Artifacts
+
+| # | Name | Category | Maturity | Location |
+|---|------|----------|----------|----------|
+| 1 | [name] | [cat] | 🔴 | [path] |
+
+## Skipped Items (with reasons)
+
+| # | Name | Reason |
+|---|------|--------|
+| 1 | [name] | [reason] |
+
+## Toolkit Status
+
+Total artifacts in toolkit: [N]
+- 🔴 Alpha: [X]
+- 🟡 Beta: [Y]
+- 🟢 Stable: [Z]
+
+## Recommendations
+
+- [Artifact X] → Consider promoting to 🟡 Beta after use in next project
+- [Pattern Y] → Needs variant for [framework Z]
+- Run next harvest after: [project/sprint/milestone]
+```
+
+### Step 6: Clean Up
+
+1. Mark extracted items as done in `TOOLKIT_HARVEST.md` (check the checkboxes)
+2. Optionally archive `TOOLKIT_HARVEST.md` to `docs/harvest-history/`
+3. Git commit: `chore: harvest [N] artifacts from [project-name]`
+
+## Git Commit Convention
+
+```
+chore: harvest [N] artifacts from [project-name]
+
+Extracted:
+- [category]: [artifact-name] (v[N])
+- [category]: [artifact-name] (new)
+```
+
+## Output
+
+- Written artifact files at their target locations
+- Updated toolkit index
+- Harvest Report at `docs/harvest-report-[date].md`
+- Checked off `TOOLKIT_HARVEST.md` items
+- Git commit with harvest summary