codeply-cli 0.3.0 → 0.4.0

package/skills/benchmark/SKILL.md

@@ -1,95 +1,95 @@
----
-name: benchmark
-description: Use this skill to measure performance baselines, detect regressions before/after PRs, and compare stack alternatives.
-license: MIT
-metadata:
-  origin: ECC
----
-
-# Benchmark — Performance Baseline & Regression Detection
-
-## When to Use
-
-- Before and after a PR to measure performance impact
-- Setting up performance baselines for a project
-- When users report "it feels slow"
-- Before a launch — ensure you meet performance targets
-- Comparing your stack against alternatives
-
-## How It Works
-
-### Mode 1: Page Performance
-
-Measures real browser metrics via browser MCP:
-
-```
-1. Navigate to each target URL
-2. Measure Core Web Vitals:
-   - LCP (Largest Contentful Paint) — target < 2.5s
-   - CLS (Cumulative Layout Shift) — target < 0.1
-   - INP (Interaction to Next Paint) — target < 200ms
-   - FCP (First Contentful Paint) — target < 1.8s
-   - TTFB (Time to First Byte) — target < 800ms
-3. Measure resource sizes:
-   - Total page weight (target < 1MB)
-   - JS bundle size (target < 200KB gzipped)
-   - CSS size
-   - Image weight
-   - Third-party script weight
-4. Count network requests
-5. Check for render-blocking resources
-```
-
-### Mode 2: API Performance
-
-Benchmarks API endpoints:
-
-```
-1. Hit each endpoint 100 times
-2. Measure: p50, p95, p99 latency
-3. Track: response size, status codes
-4. Test under load: 10 concurrent requests
-5. Compare against SLA targets
-```
-
-### Mode 3: Build Performance
-
-Measures development feedback loop:
-
-```
-1. Cold build time
-2. Hot reload time (HMR)
-3. Test suite duration
-4. TypeScript check time
-5. Lint time
-6. Docker build time
-```
-
-### Mode 4: Before/After Comparison
-
-Run before and after a change to measure impact:
-
-```
-/benchmark baseline    # saves current metrics
-# ... make changes ...
-/benchmark compare     # compares against baseline
-```
-
-Output:
-```
-| Metric | Before | After | Delta | Verdict |
-|--------|--------|-------|-------|---------|
-| LCP | 1.2s | 1.4s | +200ms | WARNING: WARN |
-| Bundle | 180KB | 175KB | -5KB | ✓ BETTER |
-| Build | 12s | 14s | +2s | WARNING: WARN |
-```
-
-## Output
-
-Stores baselines in `.ecc/benchmarks/` as JSON. Git-tracked so the team shares baselines.
-
-## Integration
-
-- CI: run `/benchmark compare` on every PR
-- Pair with `/canary-watch` for post-deploy monitoring
-- Pair with `/browser-qa` for full pre-ship checklist
+---
+name: benchmark
+description: Use this skill to measure performance baselines, detect regressions before/after PRs, and compare stack alternatives.
+license: MIT
+metadata:
+  origin: ECC
+---
+
+# Benchmark — Performance Baseline & Regression Detection
+
+## When to Use
+
+- Before and after a PR to measure performance impact
+- Setting up performance baselines for a project
+- When users report "it feels slow"
+- Before a launch — ensure you meet performance targets
+- Comparing your stack against alternatives
+
+## How It Works
+
+### Mode 1: Page Performance
+
+Measures real browser metrics via browser MCP:
+
+```
+1. Navigate to each target URL
+2. Measure Core Web Vitals:
+   - LCP (Largest Contentful Paint) — target < 2.5s
+   - CLS (Cumulative Layout Shift) — target < 0.1
+   - INP (Interaction to Next Paint) — target < 200ms
+   - FCP (First Contentful Paint) — target < 1.8s
+   - TTFB (Time to First Byte) — target < 800ms
+3. Measure resource sizes:
+   - Total page weight (target < 1MB)
+   - JS bundle size (target < 200KB gzipped)
+   - CSS size
+   - Image weight
+   - Third-party script weight
+4. Count network requests
+5. Check for render-blocking resources
+```
+
+### Mode 2: API Performance
+
+Benchmarks API endpoints:
+
+```
+1. Hit each endpoint 100 times
+2. Measure: p50, p95, p99 latency
+3. Track: response size, status codes
+4. Test under load: 10 concurrent requests
+5. Compare against SLA targets
+```
+
+### Mode 3: Build Performance
+
+Measures development feedback loop:
+
+```
+1. Cold build time
+2. Hot reload time (HMR)
+3. Test suite duration
+4. TypeScript check time
+5. Lint time
+6. Docker build time
+```
+
+### Mode 4: Before/After Comparison
+
+Run before and after a change to measure impact:
+
+```
+/benchmark baseline    # saves current metrics
+# ... make changes ...
+/benchmark compare     # compares against baseline
+```
+
+Output:
+```
+| Metric | Before | After | Delta | Verdict |
+|--------|--------|-------|-------|---------|
+| LCP | 1.2s | 1.4s | +200ms | WARNING: WARN |
+| Bundle | 180KB | 175KB | -5KB | ✓ BETTER |
+| Build | 12s | 14s | +2s | WARNING: WARN |
+```
+
+## Output
+
+Stores baselines in `.ecc/benchmarks/` as JSON. Git-tracked so the team shares baselines.
+
+## Integration
+
+- CI: run `/benchmark compare` on every PR
+- Pair with `/canary-watch` for post-deploy monitoring
+- Pair with `/browser-qa` for full pre-ship checklist

package/skills/benchmark-methodology/SKILL.md

@@ -1,191 +1,191 @@
----
-name: benchmark-methodology
-description: >-
-  Use after competitive-platform-analysis has produced a tiered competitor set.
-  Scores each competitor across nine weighted dimensions (positioning, voice,
-  visual craft, offer packaging, evidence, enterprise-readiness, thought
-  leadership, pricing, client's strategic tension) with explicit 1–5 rubrics
-  and a tension-plot. Precedes competitive-report-structure.
-license: MIT
----
-
-# Benchmark Methodology
-
-Use this skill to turn a scoped competitor set into **comparable, defensible
-scores**. Each competitor is assessed on the same nine dimensions, with
-explicit 1–5 rubrics, then captured in a uniform profile card. Consistency is
-the point: scores are only useful if the same evidence would earn the same
-number for any competitor.
-
-## When to Activate
-
-- A scoped, tiered competitor set from competitive-platform-analysis is ready to score.
-- Need comparable, evidence-anchored scores across competitors — not gut-feel rankings.
-- Client's strategic tension (the paired axes defining their target white-space) has been established.
-- Preparing to produce profile cards for assembly in competitive-report-structure.
-
-## Client positioning brief (establish first)
-
-Before scoring, establish the client's positioning brief. It supplies:
-
-- **Strategic tension** — the two axes (e.g., memorability × hireability) whose
-  intersection marks the client's target white-space. Dimension 9 is always
-  the client's named tension; report both poles separately, never averaged.
-- **Differentiator** — what makes the client's moat. This informs which
-  dimensions matter most for the client's positioning argument.
-- **Brand balance** — the intended mix of distinct strategic emphases. Strategic
-  recommendations must not break this balance without flagging it.
-
-## Why these dimensions
-
-The client competes on a **specific tension held across two poles**, not on
-service breadth. The dimensions are weighted to reflect that moat. Two
-dimensions — the tension poles — are scored **separately and never averaged
-together**, because the client's strategic question is precisely whether a rival
-achieves both simultaneously.
-
-## The nine dimensions (with weights)
-
-Weights guide synthesis emphasis, not a single blended score (avoid a false
-composite — see Bias controls). Sum = 100%.
-
-1. **Positioning clarity & distinctiveness** (18%) — Is the studio's position
-   sharp, ownable, and instantly legible? Or generic?
-2. **Brand voice / verbal distinctiveness** (15%) — Does the copy have an
-   ownable register, or is it interchangeable agency-speak?
-3. **Visual identity & site craft** (15%) — Quality and ownership of the visual
-   system; site as proof-of-craft.
-4. **Service offer & packaging** (12%) — Productized and legible (named
-   sprints/audits) vs vague. Packaging maturity.
-5. **Evidence & credibility** (12%) — Named clients, quantified outcomes,
-   case-study depth. Proof beyond assertion.
-6. **Enterprise-readiness / commercial maturity** (10%) — Signals they can land
-   and hold SaaS/fintech/B2B/enterprise work (process, logos, scale, contracts).
-7. **Thought leadership / content presence** (8%) — Owned POV: writing, talks,
-   newsletters, frameworks. Depth over volume.
-8. **Pricing transparency & engagement model** (5%) — Is pricing/engagement
-   legible? Productized vs bespoke vs opaque.
-9. **[Client's strategic tension]** (5% as a flag; **score BOTH poles,
-   report separately**) — Read the tension name and axis descriptions from the
-   client's positioning brief. Plot both; the gap is the insight. The client's
-   target quadrant is the single most important finding: who else is already
-   there?
-
-## Scoring rubric (1–5, applies to dimensions 1–8)
-
-Anchor every score to observable evidence. Generic descriptors below; adapt the
-specifics per dimension but keep the level meaning constant.
-
-- **1 — Absent / generic.** No discernible position or craft; indistinguishable
-  from a template. Active liability.
-- **2 — Below par.** Some intent but inconsistent, derivative, or unconvincing.
-  Wouldn't survive a side-by-side.
-- **3 — Competent / table-stakes.** Solid, professional, unremarkable. Meets
-  expectation, ownable by nobody.
-- **4 — Strong / distinctive.** Clearly above peers; a real strength a buyer
-  would notice and cite.
-- **5 — Category-defining.** Best-in-class, ownable, hard to imitate. Sets the
-  bar others react to.
-
-### Tension axes (dimension 9) — score each 1–5
-
-Read the axis labels and their 1/3/5 anchors from the client's positioning
-brief. Example anchors for a memorability × credibility tension:
-
-- **Memorability** — 1: forgotten instantly · 3: recognizable in context ·
-  5: unforgettable, talked-about, distinctively owned.
-- **Credibility** — 1: feels risky/amateur · 3: safe, competent,
-  unexciting · 5: enterprise-trusted, obvious safe choice.
-
-Plot competitors on the tension 2×2. The client's target quadrant is named in
-the positioning brief. Who else occupies that quadrant is the single most
-important finding of the benchmark.
-
-## How to collect the data
-
-For each competitor, work the dimensions in this order (cheapest signal first):
-
-1. **Competitor's own site** — positioning, voice, offer packaging, pricing
-   posture, named clients, manifesto/POV. Screenshot the homepage + one case
-   study.
-2. **Case studies / work** — evidence depth, quantified outcomes, client names.
-   Distinguish *asserted* ("we delivered X") from *proven* (metrics, named,
-   verifiable).
-3. **Review directories** — corroborate clients, project size, engagement model
-   → credibility & enterprise-readiness (e.g. Clutch.co or the niche equivalent).
-4. **LinkedIn** — team size/model, founder narrative, content cadence →
-   thought leadership, model.
-5. **Portfolio / craft platforms** — craft register (use the showcase native to
-   the niche: design boards, showreels, published samples, etc.).
-6. **Content channels** — newsletter/talks/writing → thought-leadership depth.
-
-**What to record per dimension:** the score, one-line justification, and the
-source link/screenshot that earned it. No score without evidence.
-
-## Bias controls
-
-- **No single composite score.** Report dimension scores and the tension plot
-  separately. A weighted average hides the asymmetry that matters.
-- **Asserted vs proven.** Downgrade credibility/evidence scores for
-  self-reported claims with no corroboration. Site copy is marketing, not fact.
-- **Aesthetic affinity bias.** Reviewers may over-score studios whose aesthetic
-  they share and under-score rivals' commercial strength. Score craft and
-  credibility independently; a "boring" site may be winning bigger clients.
-- **Recency / flashiness bias.** Award-winning, showpiece work dazzles but may
-  lack commercial depth — verify with directories/clients before scoring
-  credibility.
-- **Survivorship.** The visible, well-marketed studios aren't the whole market;
-  note strong-but-quiet operators found via directories/reviews.
-- **Calibrate across the set, not in isolation.** Before finalizing, re-read
-  scores side-by-side — a "4" must mean the same thing for every competitor.
-  Adjust outliers.
-
-## Competitor profile card (output format)
-
-Produce one card per profiled competitor — the atomic unit the report assembles
-from:
-
-```
-## <Competitor name>
-- **Profile / Tier:** <positioning stance · specialization · size band> / <Direct | Adjacent | Aspirational>
-- **One-liner:** <how they position themselves, in their words>
-- **Model / size / geography:** <solo|micro|boutique> · <region> · <pricing/engagement model>
-- **Notable clients / evidence:** <named, with proven/asserted tag>
-
-### Dimension scores
-| Dimension | Score (1–5) | Justification (1 line) | Source |
-|---|---|---|---|
-| Positioning clarity & distinctiveness | | | |
-| Brand voice / verbal distinctiveness | | | |
-| Visual identity & site craft | | | |
-| Service offer & packaging | | | |
-| Evidence & credibility | | | |
-| Enterprise-readiness / commercial maturity | | | |
-| Thought leadership / content presence | | | |
-| Pricing transparency & engagement model | | | |
-
-### Tension plot
-- **[Axis 1 from positioning brief]:** <1–5> — <why>
-- **[Axis 2 from positioning brief]:** <1–5> — <why>
-- **Quadrant:** <high/high | high-1/low-2 | low-1/high-2 | low/low>
-
-### Read for [client]
-- **Strength to learn from:** <…>
-- **Weakness to exploit / white-space it exposes:** <…>
-- **Threat to [client]:** <…>
-```
-
-Hand the completed cards plus the tension plot to `competitive-report-structure`.
-
-## Anti-Patterns
-
-- **Averaging the tension axes.** The two poles of the client's strategic tension must be scored and reported separately. Averaging destroys the insight — the gap between poles is the finding.
-- **Scoring without evidence.** Every score requires a one-line justification and a source link. A score without evidence is an opinion, not a benchmark.
-- **Creating a single composite score.** Report dimension scores individually. A weighted average hides the asymmetric strengths that matter for positioning.
-- **Applying generic rubric anchors without adapting.** The 1–5 anchors must be calibrated to the specific dimension and competitor set. The generic descriptions are a starting point, not a fixed standard.
-- **Running before the competitor set is scoped.** Use competitive-platform-analysis first to produce a tiered, pruned set. Scoring an unscoped list wastes effort on irrelevant competitors.
-
-## Related Skills
-
-- `competitive-platform-analysis` — the prerequisite; produces the tiered competitor set this skill scores.
-- `competitive-report-structure` — the next step; assembles the scored profile cards into a client-deliverable report.
+---
+name: benchmark-methodology
+description: >-
+  Use after competitive-platform-analysis has produced a tiered competitor set.
+  Scores each competitor across nine weighted dimensions (positioning, voice,
+  visual craft, offer packaging, evidence, enterprise-readiness, thought
+  leadership, pricing, client's strategic tension) with explicit 1–5 rubrics
+  and a tension-plot. Precedes competitive-report-structure.
+license: MIT
+---
+
+# Benchmark Methodology
+
+Use this skill to turn a scoped competitor set into **comparable, defensible
+scores**. Each competitor is assessed on the same nine dimensions, with
+explicit 1–5 rubrics, then captured in a uniform profile card. Consistency is
+the point: scores are only useful if the same evidence would earn the same
+number for any competitor.
+
+## When to Activate
+
+- A scoped, tiered competitor set from competitive-platform-analysis is ready to score.
+- Need comparable, evidence-anchored scores across competitors — not gut-feel rankings.
+- Client's strategic tension (the paired axes defining their target white-space) has been established.
+- Preparing to produce profile cards for assembly in competitive-report-structure.
+
+## Client positioning brief (establish first)
+
+Before scoring, establish the client's positioning brief. It supplies:
+
+- **Strategic tension** — the two axes (e.g., memorability × hireability) whose
+  intersection marks the client's target white-space. Dimension 9 is always
+  the client's named tension; report both poles separately, never averaged.
+- **Differentiator** — what makes the client's moat. This informs which
+  dimensions matter most for the client's positioning argument.
+- **Brand balance** — the intended mix of distinct strategic emphases. Strategic
+  recommendations must not break this balance without flagging it.
+
+## Why these dimensions
+
+The client competes on a **specific tension held across two poles**, not on
+service breadth. The dimensions are weighted to reflect that moat. Two
+dimensions — the tension poles — are scored **separately and never averaged
+together**, because the client's strategic question is precisely whether a rival
+achieves both simultaneously.
+
+## The nine dimensions (with weights)
+
+Weights guide synthesis emphasis, not a single blended score (avoid a false
+composite — see Bias controls). Sum = 100%.
+
+1. **Positioning clarity & distinctiveness** (18%) — Is the studio's position
+   sharp, ownable, and instantly legible? Or generic?
+2. **Brand voice / verbal distinctiveness** (15%) — Does the copy have an
+   ownable register, or is it interchangeable agency-speak?
+3. **Visual identity & site craft** (15%) — Quality and ownership of the visual
+   system; site as proof-of-craft.
+4. **Service offer & packaging** (12%) — Productized and legible (named
+   sprints/audits) vs vague. Packaging maturity.
+5. **Evidence & credibility** (12%) — Named clients, quantified outcomes,
+   case-study depth. Proof beyond assertion.
+6. **Enterprise-readiness / commercial maturity** (10%) — Signals they can land
+   and hold SaaS/fintech/B2B/enterprise work (process, logos, scale, contracts).
+7. **Thought leadership / content presence** (8%) — Owned POV: writing, talks,
+   newsletters, frameworks. Depth over volume.
+8. **Pricing transparency & engagement model** (5%) — Is pricing/engagement
+   legible? Productized vs bespoke vs opaque.
+9. **[Client's strategic tension]** (5% as a flag; **score BOTH poles,
+   report separately**) — Read the tension name and axis descriptions from the
+   client's positioning brief. Plot both; the gap is the insight. The client's
+   target quadrant is the single most important finding: who else is already
+   there?
+
+## Scoring rubric (1–5, applies to dimensions 1–8)
+
+Anchor every score to observable evidence. Generic descriptors below; adapt the
+specifics per dimension but keep the level meaning constant.
+
+- **1 — Absent / generic.** No discernible position or craft; indistinguishable
+  from a template. Active liability.
+- **2 — Below par.** Some intent but inconsistent, derivative, or unconvincing.
+  Wouldn't survive a side-by-side.
+- **3 — Competent / table-stakes.** Solid, professional, unremarkable. Meets
+  expectation, ownable by nobody.
+- **4 — Strong / distinctive.** Clearly above peers; a real strength a buyer
+  would notice and cite.
+- **5 — Category-defining.** Best-in-class, ownable, hard to imitate. Sets the
+  bar others react to.
+
+### Tension axes (dimension 9) — score each 1–5
+
+Read the axis labels and their 1/3/5 anchors from the client's positioning
+brief. Example anchors for a memorability × credibility tension:
+
+- **Memorability** — 1: forgotten instantly · 3: recognizable in context ·
+  5: unforgettable, talked-about, distinctively owned.
+- **Credibility** — 1: feels risky/amateur · 3: safe, competent,
+  unexciting · 5: enterprise-trusted, obvious safe choice.
+
+Plot competitors on the tension 2×2. The client's target quadrant is named in
+the positioning brief. Who else occupies that quadrant is the single most
+important finding of the benchmark.
+
+## How to collect the data
+
+For each competitor, work the dimensions in this order (cheapest signal first):
+
+1. **Competitor's own site** — positioning, voice, offer packaging, pricing
+   posture, named clients, manifesto/POV. Screenshot the homepage + one case
+   study.
+2. **Case studies / work** — evidence depth, quantified outcomes, client names.
+   Distinguish *asserted* ("we delivered X") from *proven* (metrics, named,
+   verifiable).
+3. **Review directories** — corroborate clients, project size, engagement model
+   → credibility & enterprise-readiness (e.g. Clutch.co or the niche equivalent).
+4. **LinkedIn** — team size/model, founder narrative, content cadence →
+   thought leadership, model.
+5. **Portfolio / craft platforms** — craft register (use the showcase native to
+   the niche: design boards, showreels, published samples, etc.).
+6. **Content channels** — newsletter/talks/writing → thought-leadership depth.
+
+**What to record per dimension:** the score, one-line justification, and the
+source link/screenshot that earned it. No score without evidence.
+
+## Bias controls
+
+- **No single composite score.** Report dimension scores and the tension plot
+  separately. A weighted average hides the asymmetry that matters.
+- **Asserted vs proven.** Downgrade credibility/evidence scores for
+  self-reported claims with no corroboration. Site copy is marketing, not fact.
+- **Aesthetic affinity bias.** Reviewers may over-score studios whose aesthetic
+  they share and under-score rivals' commercial strength. Score craft and
+  credibility independently; a "boring" site may be winning bigger clients.
+- **Recency / flashiness bias.** Award-winning, showpiece work dazzles but may
+  lack commercial depth — verify with directories/clients before scoring
+  credibility.
+- **Survivorship.** The visible, well-marketed studios aren't the whole market;
+  note strong-but-quiet operators found via directories/reviews.
+- **Calibrate across the set, not in isolation.** Before finalizing, re-read
+  scores side-by-side — a "4" must mean the same thing for every competitor.
+  Adjust outliers.
+
+## Competitor profile card (output format)
+
+Produce one card per profiled competitor — the atomic unit the report assembles
+from:
+
+```
+## <Competitor name>
+- **Profile / Tier:** <positioning stance · specialization · size band> / <Direct | Adjacent | Aspirational>
+- **One-liner:** <how they position themselves, in their words>
+- **Model / size / geography:** <solo|micro|boutique> · <region> · <pricing/engagement model>
+- **Notable clients / evidence:** <named, with proven/asserted tag>
+
+### Dimension scores
+| Dimension | Score (1–5) | Justification (1 line) | Source |
+|---|---|---|---|
+| Positioning clarity & distinctiveness | | | |
+| Brand voice / verbal distinctiveness | | | |
+| Visual identity & site craft | | | |
+| Service offer & packaging | | | |
+| Evidence & credibility | | | |
+| Enterprise-readiness / commercial maturity | | | |
+| Thought leadership / content presence | | | |
+| Pricing transparency & engagement model | | | |
+
+### Tension plot
+- **[Axis 1 from positioning brief]:** <1–5> — <why>
+- **[Axis 2 from positioning brief]:** <1–5> — <why>
+- **Quadrant:** <high/high | high-1/low-2 | low-1/high-2 | low/low>
+
+### Read for [client]
+- **Strength to learn from:** <…>
+- **Weakness to exploit / white-space it exposes:** <…>
+- **Threat to [client]:** <…>
+```
+
+Hand the completed cards plus the tension plot to `competitive-report-structure`.
+
+## Anti-Patterns
+
+- **Averaging the tension axes.** The two poles of the client's strategic tension must be scored and reported separately. Averaging destroys the insight — the gap between poles is the finding.
+- **Scoring without evidence.** Every score requires a one-line justification and a source link. A score without evidence is an opinion, not a benchmark.
+- **Creating a single composite score.** Report dimension scores individually. A weighted average hides the asymmetric strengths that matter for positioning.
+- **Applying generic rubric anchors without adapting.** The 1–5 anchors must be calibrated to the specific dimension and competitor set. The generic descriptions are a starting point, not a fixed standard.
+- **Running before the competitor set is scoped.** Use competitive-platform-analysis first to produce a tiered, pruned set. Scoring an unscoped list wastes effort on irrelevant competitors.
+
+## Related Skills
+
+- `competitive-platform-analysis` — the prerequisite; produces the tiered competitor set this skill scores.
+- `competitive-report-structure` — the next step; assembles the scored profile cards into a client-deliverable report.