@dzhechkov/p-replicator 1.0.0

package/templates/.claude/skills/pipeline-forge/references/quality-gates.md

@@ -0,0 +1,268 @@
+# Quality Gates Reference
+
+Patterns for validation, scoring, verdicts, and blocking thresholds in AI pipelines.
+Extracted from `requirements-validator` and `doc-validator` in PU Unicorn Replicate.
+
+---
+
+## What is a Quality Gate?
+
+A quality gate is a checkpoint between pipeline phases that:
+1. **Evaluates** output against defined criteria
+2. **Scores** the output numerically
+3. **Renders a verdict** (READY / CAVEATS / BLOCKED)
+4. **Blocks progression** if quality is insufficient
+5. **Provides actionable feedback** for improvement
+
+---
+
+## Gate Structure
+
+```
+PHASE OUTPUT
+    ↓
+┌──────────────────────┐
+│    QUALITY GATE       │
+│                       │
+│  1. Apply Criteria    │ ← INVEST, SMART, custom
+│  2. Score (0-100)     │ ← per-item and aggregate
+│  3. Render Verdict    │ ← READY / CAVEATS / BLOCKED
+│  4. Decision          │ ← proceed / fix / abort
+│                       │
+└──────────────────────┘
+    ↓
+NEXT PHASE (if READY/CAVEATS)
+```
+
+---
+
+## Scoring System Design
+
+### Scoring Scale
+
+| Score | Rating | Meaning | Action |
+|-------|--------|---------|--------|
+| 90-100 | Excellent | Exceeds requirements | Proceed immediately |
+| 70-89 | Good | Meets requirements | Proceed with minor notes |
+| 50-69 | Fair | Partially meets | Fix issues, then proceed |
+| **0-49** | **Poor** | **Fails requirements** | **BLOCKED — must fix** |
+
+### Scoring Formula
+
+```
+total_score = Σ(criterion_weight × criterion_score) / Σ(weights)
+```
+
+**Example (requirements validation):**
+```
+score = (INVEST_score × 0.50) + (SMART_score × 0.30) + (coverage_score × 0.20)
+```
+
+### Per-Criterion Scoring
+
+Each criterion is binary (pass/fail) or graduated:
+
+**Binary example (INVEST):**
+```
+| Criterion | Pass | Issue |
+|-----------|------|-------|
+| Independent | ✓ | - |
+| Negotiable | ✓ | - |
+| Valuable | ✗ | No "so that" clause |
+| Estimable | ✓ | - |
+| Small | ✗ | "entire module" |
+| Testable | ✗ | No acceptance criteria |
+
+Score: 3/6 = 50% → 50 × 0.50 weight = 25 points
+```
+
+---
+
+## Verdict System
+
+### Three-Tier Verdicts
+
+| Verdict | Symbol | Conditions | Action |
+|---------|--------|-----------|--------|
+| **READY** | 🟢 | All items ≥50, average ≥70, no contradictions | Proceed to next phase |
+| **CAVEATS** | 🟡 | Warnings exist, no blocked items, limitations described | Proceed with notes |
+| **NEEDS WORK** | 🔴 | Any blocked item (score <50) exists | Return to previous phase |
+
+### Verdict Decision Logic
+
+```
+IF any_item.score < 50:
+    verdict = NEEDS_WORK (🔴)
+ELIF average_score < 70:
+    verdict = NEEDS_WORK (🔴)
+ELIF any_item.score < 70:
+    verdict = CAVEATS (🟡)
+ELSE:
+    verdict = READY (🟢)
+```
+
+---
+
+## Iterative Validation
+
+When output fails a quality gate, use iterative fix-and-revalidate:
+
+```
+FOR iteration = 1 TO max_iterations (typically 3):
+    1. ANALYZE — run all validators (parallel swarm)
+    2. AGGREGATE — merge results, build Gap Register
+    3. CHECK — apply verdict logic
+    4. IF verdict == READY or CAVEATS:
+         EXIT with verdict
+    5. FIX — resolve gaps in source material
+    6. RE-VALIDATE — go to step 1
+
+IF max_iterations reached AND still NEEDS_WORK:
+    EXIT with NEEDS_WORK + Gap Register
+```
+
+### Gap Register Format
+
+```markdown
+| ID | Source | Issue | Severity | Status | Fix |
+|----|--------|-------|----------|--------|-----|
+| G-001 | PRD.md | Missing NFRs | BLOCKED | Fixed | Added performance section |
+| G-002 | Architecture.md | No DB schema | WARNING | Open | Needs data model |
+```
+
+---
+
+## Common Quality Criteria
+
+### For Requirements (INVEST)
+
+| Criterion | Question | Red Flags |
+|-----------|----------|-----------|
+| **I**ndependent | Can develop separately? | "after X is done", "depends on" |
+| **N**egotiable | Open to discussion? | "must be exactly", rigid specs |
+| **V**aluable | Clear user benefit? | No "so that" clause |
+| **E**stimable | Can estimate effort? | "system should be fast" |
+| **S**mall | Fits in one sprint? | "entire module", "all users" |
+| **T**estable | Has pass/fail criteria? | No acceptance criteria |
+
+### For Acceptance Criteria (SMART)
+
+| Criterion | Question | Red Flags |
+|-----------|----------|-----------|
+| **S**pecific | Clear, unambiguous? | "fast", "easy", "user-friendly" |
+| **M**easurable | Has metrics? | No numbers/thresholds |
+| **A**chievable | Technically feasible? | "100% uptime", "instant" |
+| **R**elevant | Supports story goal? | Unrelated to user value |
+| **T**ime-bound | Has timing context? | No response times |
+
+### For Architecture
+
+| Criterion | Question |
+|-----------|----------|
+| Constraints compliance | Matches target architecture (monolith/micro/etc.)? |
+| Completeness | All layers covered (frontend, backend, DB, infra)? |
+| Consistency | Tech stack choices don't contradict? |
+| Security | Authentication, authorization, encryption addressed? |
+| Scalability | Growth path defined? |
+
+### For Cross-Document Consistency
+
+| Check | What to verify |
+|-------|---------------|
+| Terminology | Same terms used across all documents? |
+| Feature coverage | Every PRD feature has pseudocode + architecture? |
+| Story coverage | Every user story has test scenario? |
+| Stack alignment | Architecture.md stack matches Pseudocode.md assumptions? |
+| Contradiction | No conflicting statements across documents? |
+
+---
+
+## Vague Terms Detection
+
+Always flag these and suggest specific replacements:
+
+| Vague Term | Specific Replacement |
+|-----------|---------------------|
+| "fast" | "<200ms p95 response time" |
+| "easy" | "completed in <3 clicks" |
+| "user-friendly" | "passes usability test with >80% task completion" |
+| "secure" | "passes OWASP Top 10 security scan" |
+| "scalable" | "handles 10,000 concurrent users" |
+| "reliable" | "99.9% uptime SLA" |
+| "responsive" | "renders above-the-fold in <1.5s on 3G" |
+| "intuitive" | "zero training required, <30s to first action" |
+
+---
+
+## Validation Report Format
+
+```markdown
+# Validation Report
+
+## Summary
+- Items analyzed: [N]
+- Average score: [XX]/100
+- Blocked: [N] (score <50)
+- Warnings: [N] (score 50-69)
+- Ready: [N] (score ≥70)
+- Iterations: [N] of max 3
+
+## Results
+
+| Item | Score | Criteria Met | Status |
+|------|-------|-------------|--------|
+| [item-1] | 92/100 | 6/6 INVEST, 5/5 SMART | READY |
+| [item-2] | 45/100 | 3/6 INVEST, 2/5 SMART | BLOCKED |
+
+## Gap Register
+
+| ID | Source | Issue | Severity | Status |
+|----|--------|-------|----------|--------|
+
+## Cross-Document Consistency
+
+| Check | Status | Notes |
+|-------|--------|-------|
+
+## Readiness Verdict
+
+🟢 READY / 🟡 CAVEATS / 🔴 NEEDS WORK
+
+[Explanation of verdict]
+```
+
+---
+
+## Designing Custom Quality Gates
+
+When creating a quality gate for a new domain:
+
+1. **Identify criteria** — what makes output "good" in this domain?
+2. **Weight criteria** — which matter most? (sum to 100%)
+3. **Define scoring** — how to evaluate each criterion (binary or graduated)
+4. **Set thresholds** — what score blocks progression?
+5. **Define verdicts** — what are the possible outcomes?
+6. **Design iteration** — how many fix cycles? Max iterations?
+7. **Write report template** — what does the validation output look like?
+
+### Template
+
+```markdown
+## Quality Gate: [Gate Name]
+
+### Criteria (weighted)
+| Criterion | Weight | Scoring | Threshold |
+|-----------|--------|---------|-----------|
+| [criterion-1] | 40% | 0-100 | ≥50 (blocking) |
+| [criterion-2] | 30% | Pass/Fail | Must pass |
+| [criterion-3] | 30% | 0-100 | ≥60 (warning) |
+
+### Verdicts
+| Verdict | Conditions | Action |
+|---------|-----------|--------|
+| READY | All ≥ thresholds, avg ≥ 70 | Proceed |
+| CAVEATS | Warnings, no blocked | Proceed with notes |
+| BLOCKED | Any below threshold | Fix and re-validate |
+
+### Max Iterations: 3
+```

package/templates/.claude/skills/pipeline-forge/references/skill-anatomy.md

@@ -0,0 +1,292 @@
+# Skill Anatomy Reference
+
+How to structure composable skills for Claude Code. Based on analysis of 8 production
+skills from the PU Unicorn Replicate methodology.
+
+---
+
+## Minimum Viable Skill
+
+The simplest possible skill:
+
+```
+skill-name/
+└── SKILL.md
+```
+
+A single `SKILL.md` file with:
+
+```markdown
+---
+name: my-skill
+description: >
+  One paragraph. What it does. When to use it. Trigger words.
+---
+
+# My Skill Name
+
+One sentence of purpose.
+
+## When to Use
+
+- Trigger pattern 1
+- Trigger pattern 2
+
+## Input
+
+[What the skill receives]
+
+## Execution
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Output
+
+[Structured output format]
+```
+
+---
+
+## Full Skill Structure
+
+For complex skills:
+
+```
+skill-name/
+├── SKILL.md                    # Entry point (REQUIRED)
+├── references/                 # Supporting knowledge (OPTIONAL)
+│   ├── methodology.md          # Frameworks, criteria, scoring
+│   ├── best-practices.md       # Domain expertise
+│   └── templates.md            # Reference templates
+├── templates/                  # Output templates (OPTIONAL)
+│   ├── output-template.md      # Template with {{PLACEHOLDERS}}
+│   └── report-template.md
+├── modules/                    # Sub-phases (OPTIONAL)
+│   ├── 01-phase-one.md         # Numbered for ordering
+│   ├── 02-phase-two.md
+│   └── 03-phase-three.md
+├── examples/                   # Few-shot examples (OPTIONAL)
+│   └── example-output.md
+└── scripts/                    # Executable helpers (OPTIONAL)
+    └── helper.sh
+```
+
+---
+
+## SKILL.md Sections (Recommended Order)
+
+### 1. Frontmatter (REQUIRED)
+
+```yaml
+---
+name: skill-name-kebab-case
+description: >
+  One paragraph (2-5 sentences). What the skill does, when to use it,
+  trigger words/patterns. This appears in skill listings.
+---
+```
+
+### 2. Title and Purpose (REQUIRED)
+
+```markdown
+# Skill Name: Short Description
+
+One sentence explaining what this skill transforms (input → output).
+```
+
+### 3. Architecture (RECOMMENDED for complex skills)
+
+```markdown
+## Architecture
+
+\`\`\`
+skill-name/
+├── SKILL.md
+├── references/
+│   └── ...
+└── templates/
+    └── ...
+\`\`\`
+```
+
+### 4. External Dependencies (IF ANY)
+
+```markdown
+## External Dependencies (loaded via view() at runtime)
+
+| Phase | Skill | Path | Purpose |
+|-------|-------|------|---------|
+| Phase 1 | explore | `.claude/skills/explore/SKILL.md` | Task clarification |
+
+**Fallbacks:**
+- `explore` unavailable → built-in 3-5 questions
+```
+
+### 5. When to Use (REQUIRED)
+
+```markdown
+## When to Use
+
+**Trigger Patterns:**
+- "keyword phrase 1"
+- "keyword phrase 2"
+- "keyword phrase 3" (also in Russian/other language if bilingual)
+
+**Use Cases:**
+- Use case 1
+- Use case 2
+```
+
+### 6. Operating Modes (IF MULTIPLE)
+
+```markdown
+## Operating Modes
+
+| Mode | Triggers | Checkpoints | Time |
+|------|----------|-------------|------|
+| AUTO | "auto", "fast" | 0 | ~5 min |
+| MANUAL | "manual", "step by step" | N | ~20 min |
+```
+
+### 7. Workflow / Pipeline (REQUIRED)
+
+```markdown
+## Workflow
+
+\`\`\`
+INPUT → PHASE 1 → PHASE 2 → ... → OUTPUT
+\`\`\`
+
+### Phase 1: [Name]
+
+**Goal:** [one sentence]
+
+**Process:**
+1. [step]
+2. [step]
+
+**Output:**
+[structured format]
+
+**Checkpoint (MANUAL mode):**
+\`\`\`
+═════════════════════════════════════════════
+⏸️ CHECKPOINT 1: [Phase Name]
+[summary]
+"ок" — next | "уточни X" — clarify
+═════════════════════════════════════════════
+\`\`\`
+```
+
+### 8. Output Format (REQUIRED)
+
+```markdown
+## Output Format
+
+\`\`\`markdown
+## [Output Title]
+
+### Section 1
+[template]
+
+### Section 2
+| Column | Column |
+|--------|--------|
+\`\`\`
+```
+
+### 9. Anti-Patterns (RECOMMENDED)
+
+```markdown
+## Anti-Patterns
+
+❌ [What NOT to do — reason]
+❌ [What NOT to do — reason]
+```
+
+### 10. Quality Standards (RECOMMENDED)
+
+```markdown
+## Quality Standards
+
+- [ ] Check 1
+- [ ] Check 2
+- [ ] Check 3
+```
+
+### 11. Integration Notes (IF APPLICABLE)
+
+```markdown
+## Integration Notes
+
+After this skill, hand off to:
+- `skill-A` for [purpose]
+- `skill-B` for [purpose]
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Skill directory | `kebab-case` | `problem-solver-enhanced` |
+| SKILL.md | Always uppercase | `SKILL.md` |
+| References | `kebab-case.md` | `scoring-system.md` |
+| Templates | `kebab-case.md` | `prd-template.md` |
+| Modules | `NN-kebab-case.md` | `01-intelligence.md` |
+| Examples | `descriptive-name.md` | `noom-cjm-example.md` |
+| Scripts | `kebab-case.ext` | `assess-code.sh` |
+
+---
+
+## Skill Size Guidelines
+
+| Complexity | SKILL.md Lines | Subdirectories | Example |
+|------------|---------------|----------------|---------|
+| Simple | 50-150 | None | `explore` |
+| Medium | 150-400 | references/ | `requirements-validator` |
+| Complex | 400-600 | references/ + templates/ | `sparc-prd-mini` |
+| Very Complex | 300-400 + modules/ | All | `reverse-engineering-unicorn` |
+
+**Rule:** If SKILL.md exceeds 600 lines, split logic into `modules/` and keep
+SKILL.md as orchestrator (~200-300 lines).
+
+---
+
+## Frontmatter Description Tips
+
+**Good descriptions include:**
+- What the skill does (1 sentence)
+- When to use it (conditions/triggers)
+- Trigger words/phrases for auto-activation
+
+**Example:**
+```yaml
+description: >
+  Validate requirements for testability, completeness, and clarity using
+  INVEST and SMART criteria. Generate BDD scenarios from user stories.
+  Use when: validating user stories before development, checking acceptance
+  criteria quality, generating Gherkin/BDD scenarios. Triggers: "validate
+  requirements", "check user story", "generate BDD", "INVEST check".
+  Blocks requirements with score <50 from proceeding.
+```
+
+---
+
+## Checklist: Is My Skill Well-Structured?
+
+- [ ] Has SKILL.md with frontmatter (name + description)
+- [ ] Purpose is clear in 1 sentence
+- [ ] Trigger patterns listed (when to activate)
+- [ ] Input format documented
+- [ ] Output format documented with template
+- [ ] Execution steps are numbered and clear
+- [ ] Anti-patterns listed (what NOT to do)
+- [ ] If has dependencies → fallback strategy documented
+- [ ] If complex → split into modules/
+- [ ] If generates output → templates/ provided
+- [ ] References are read-only knowledge, not executable logic
+- [ ] No hardcoded paths (use path mapping if cross-environment)

package/templates/.claude/skills/pipeline-forge/templates/agent-template.md

@@ -0,0 +1,60 @@
+# {{AGENT_NAME}} Agent
+
+{{ONE_SENTENCE_PURPOSE}}
+
+## When to Use
+
+{{ACTIVATION_CONDITIONS}}
+
+## Skill Reference
+
+Uses `{{SKILL_NAME}}` skill.
+Read from: `.claude/skills/{{SKILL_NAME}}/SKILL.md`
+
+## Responsibilities
+
+1. **{{RESPONSIBILITY_1}}** — {{DESCRIPTION}}
+2. **{{RESPONSIBILITY_2}}** — {{DESCRIPTION}}
+3. **{{RESPONSIBILITY_3}}** — {{DESCRIPTION}}
+
+## Scope
+
+| Aspect | Value |
+|--------|-------|
+| Input | {{WHAT_AGENT_RECEIVES}} |
+| Output | {{WHAT_AGENT_PRODUCES}} |
+| Criteria | {{PASS_FAIL_CRITERIA}} |
+| Independence | {{FULL_OR_DEPENDS_ON}} |
+
+## Process
+
+```
+1. {{STEP_1}}
+2. {{STEP_2}}
+3. {{STEP_3}}
+4. {{STEP_4}}
+```
+
+## Output Format
+
+```markdown
+## {{AGENT_NAME}} Report
+
+### Summary
+{{SUMMARY_TEMPLATE}}
+
+### Findings
+| Item | Status | Details |
+|------|--------|---------|
+
+### Verdict
+{{VERDICT_FORMAT}}
+```
+
+## Anti-Hallucination Rules
+
+- Search first — never answer from memory for facts
+- Source attribution — every fact → URL
+- "NOT FOUND" > fabrication
+- Hypotheses marked with `[H]` tag
+- Confidence score at end

package/templates/.claude/skills/pipeline-forge/templates/command-template.md

@@ -0,0 +1,80 @@
+---
+description: >
+  {{COMMAND_DESCRIPTION}}
+  $ARGUMENTS: {{ARGUMENTS_DESCRIPTION}}
+---
+
+# /{{COMMAND_NAME}} $ARGUMENTS
+
+## Role
+
+{{ROLE_DESCRIPTION}}
+
+## Skills (loaded from .claude/skills/)
+
+| Skill | Path | Phase |
+|-------|------|-------|
+| {{SKILL_1}} | `.claude/skills/{{SKILL_1}}/SKILL.md` | Phase {{N}} |
+| {{SKILL_2}} | `.claude/skills/{{SKILL_2}}/SKILL.md` | Phase {{N}} |
+
+## Pipeline
+
+```
+INPUT → [{{PHASE_1}}] → [{{PHASE_2}}] → ... → OUTPUT
+         {{SKILL_1}}     {{SKILL_2}}
+```
+
+## Execution
+
+### Start
+
+1. Briefly explain the phases
+2. Determine context from $ARGUMENTS
+3. Begin with Phase 1
+
+### Phase 1: {{PHASE_1_NAME}}
+
+Read the skill: `.claude/skills/{{SKILL_1}}/SKILL.md`
+
+**Goal:** {{GOAL}}
+
+**Pass context:**
+```yaml
+{{CONTEXT_TO_PASS}}
+```
+
+**Output location:** `{{OUTPUT_PATH}}`
+
+Git commit: `{{COMMIT_TYPE}}: {{COMMIT_MESSAGE}}`
+
+**Checkpoint:**
+```
+═══════════════════════════════════════════════════════════════
+✅ PHASE 1: {{PHASE_1_NAME}}
+{{SUMMARY}}
+⏸️ "ок" — next | "превью [filename]" — show file
+═══════════════════════════════════════════════════════════════
+```
+
+### Phase N: {{PHASE_N_NAME}}
+
+<!-- Repeat for each phase -->
+
+## Checkpoint Commands
+
+| Command | Action |
+|---------|--------|
+| `ок` | Next phase |
+| `превью [filename]` | View generated file |
+
+## Critical Rules
+
+### ALWAYS
+- Read skill SKILL.md before executing
+- Checkpoint after each phase
+- Write output to specified paths
+
+### NEVER
+- Don't skip validation phases
+- Don't generate from memory (read docs)
+- Don't overwrite existing template files