agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/migration/skills/agileflow-migration/references/version-compatibility-matrix.md

@@ -0,0 +1,155 @@
+# Version Compatibility Matrix
+
+**Load this when:** Planning a version upgrade, evaluating breaking changes, or defining a deprecation timeline.
+
+## Semver Rules Quick Reference
+
+| Version segment | When to bump                    | Example change                                       |
+| --------------- | ------------------------------- | ---------------------------------------------------- |
+| MAJOR (X.0.0)   | Breaking change                 | Removed API, changed required field, dropped runtime |
+| MINOR (x.Y.0)   | New backward-compatible feature | Added endpoint, new optional field                   |
+| PATCH (x.y.Z)   | Backward-compatible bug fix     | Fixed incorrect response, corrected type             |
+| Pre-release     | Unstable / experimental         | `2.0.0-alpha.1`, `1.5.0-rc.2`                        |
+
+**Rule:** If in doubt whether a change is breaking, treat it as breaking (MAJOR).
+
+---
+
+## Breaking Change Detection Checklist
+
+### API / REST
+
+- [ ] Removed endpoint
+- [ ] Renamed endpoint path
+- [ ] Changed HTTP method for an operation
+- [ ] Removed required or optional field from response
+- [ ] Changed field type (string → integer, etc.)
+- [ ] Changed field name
+- [ ] Made previously optional request field required
+- [ ] Changed authentication mechanism
+- [ ] Changed pagination scheme
+- [ ] Changed error response format
+
+### Library / SDK
+
+- [ ] Removed exported function, class, or constant
+- [ ] Renamed exported symbol
+- [ ] Changed function signature (parameter type, order, or count)
+- [ ] Changed return type
+- [ ] Changed thrown error types
+- [ ] Removed support for a runtime version (Node, browser)
+- [ ] Changed peer dependency requirements
+
+### Database schema
+
+- [ ] Dropped column or table
+- [ ] Renamed column or table
+- [ ] Changed column type in incompatible way
+- [ ] Added NOT NULL constraint to existing column (without default)
+- [ ] Changed primary key
+
+---
+
+## Deprecation Timeline Standards
+
+| Phase         | Duration         | User expectation                          |
+| ------------- | ---------------- | ----------------------------------------- |
+| Announcement  | —                | Feature marked deprecated in docs + logs  |
+| Notice period | ≥1 MINOR version | Warning in responses/console; still works |
+| Removal       | NEXT MAJOR       | Removed entirely                          |
+
+**Minimum deprecation period:** 1 full MINOR version release cycle.
+**Recommended:** 6 months notice before removal for public APIs.
+
+### Deprecation notice format (in code)
+
+```js
+/**
+ * @deprecated Use `newFunction()` instead. Will be removed in v3.0.
+ * @see https://docs.example.com/migration/v2-to-v3
+ */
+function oldFunction() { ... }
+```
+
+### Deprecation notice in API response header
+
+```
+Deprecation: true
+Sunset: Sat, 01 Jan 2026 00:00:00 GMT
+Link: <https://docs.example.com/migration>; rel="successor-version"
+```
+
+---
+
+## Node.js Version Support Matrix (template)
+
+| Package version | Node 18 | Node 20 | Node 22 | Notes               |
+| --------------- | ------- | ------- | ------- | ------------------- |
+| v3.x (current)  | Yes     | Yes     | Yes     | Active support      |
+| v2.x            | Yes     | Yes     | No      | Security fixes only |
+| v1.x            | No      | No      | No      | EOL                 |
+
+**Policy:** Support Node LTS versions that have not reached EOL.
+[Node.js release schedule](https://nodejs.org/en/about/previous-releases)
+
+---
+
+## Peer Dependency Compatibility
+
+```json
+// package.json
+{
+  "peerDependencies": {
+    "react": ">=17.0.0 <20.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  }
+}
+```
+
+| Version range      | Meaning                           |
+| ------------------ | --------------------------------- |
+| `>=17.0.0`         | 17+ with no upper bound           |
+| `^17.0.0`          | 17.x only                         |
+| `>=17.0.0 <20.0.0` | 17, 18, 19 — explicit upper bound |
+| `*`                | Any version (avoid for peers)     |
+
+---
+
+## Migration Path Matrix (template)
+
+Use this to communicate supported upgrade paths:
+
+| From | To   | Supported    | Migration guide           |
+| ---- | ---- | ------------ | ------------------------- |
+| v1.x | v2.x | Yes          | [v1→v2 guide](#)          |
+| v2.x | v3.x | Yes          | [v2→v3 guide](#)          |
+| v1.x | v3.x | Yes (2-step) | Upgrade to v2 first       |
+| v0.x | v3.x | No           | Manual migration required |
+
+---
+
+## Changelog Entry Format for Breaking Changes
+
+```markdown
+## [3.0.0] - 2025-06-01
+
+### BREAKING CHANGES
+
+- **Removed** `getUser()` — use `fetchUser()` instead (#123)
+- **Changed** `config.timeout` now in milliseconds, was seconds (#456)
+- **Dropped** Node 16 support — Node 18+ required
+
+### Migration Guide
+
+See https://docs.example.com/migration/v2-to-v3
+
+### Added
+
+- New `fetchUser()` with retry logic and timeout (#123)
+
+### Fixed
+
+- Config validation no longer throws on undefined optional fields
+```

package/content/plugins/migration/skills/agileflow-migration/workflows/plan.md

@@ -0,0 +1,73 @@
+# Plan Workflow — Migration Planning
+
+**Triggers:** "plan the migration to React 18", "create a migration plan", "how do we upgrade to Next.js 15", "migration roadmap for TypeScript 5.5", "step-by-step upgrade plan"
+
+**Goal:** Generate a detailed migration plan with step-by-step execution order, dependency mapping, risk assessment, rollback strategies, and effort estimates.
+
+## Inputs needed
+
+| Input  | Required | How to get it                                                               |
+| ------ | -------- | --------------------------------------------------------------------------- |
+| target | Yes      | Ask: "What are you migrating to? (e.g., react@18, next@15, typescript@5.5)" |
+| scope  | No       | Default: full. Options: full (all at once), incremental (phased)            |
+
+## Steps
+
+1. Ask for the migration target if not provided.
+
+2. Read the current state: `package.json` for current versions, key source files to understand usage patterns.
+
+3. Research the migration path. Look up official migration guides for the target upgrade, known breaking changes between current and target versions, community-reported issues, and workarounds.
+
+4. Ask: "Migration scope?" Options: [A] Full migration (all at once — recommended for small projects), [B] Incremental (phased — recommended for large projects or high-risk upgrades).
+
+5. Map dependencies between migration steps — which steps must happen before others, which can run in parallel, which affect shared code.
+
+6. Assess risk for each step:
+   - **High**: data migration, schema changes, auth changes, API contract changes
+   - **Medium**: dependency swaps, config changes, API client changes
+   - **Low**: syntax updates, import path changes, type annotation updates
+
+7. Design a rollback strategy for each high-risk step.
+
+8. Generate the Migration Plan document:
+
+   ```
+   # Migration Plan: [Target]
+   Generated / Current State / Target State / Estimated Effort / Overall Risk
+
+   ## Pre-Migration Checklist
+   - [ ] All tests passing before starting
+   - [ ] Feature branch created
+   - [ ] Backup/snapshot if applicable
+
+   ## Phase 1: [Description]
+   Step 1: [title] — Risk: Low/Med/High — Effort: Xh
+     - What to do
+     - Rollback: [how to undo]
+   Step 2: ...
+
+   ## Validation Checkpoints
+   [After each phase: tests to run, things to verify]
+
+   ## Rollback Plan
+   [How to revert entirely if needed]
+   ```
+
+9. Show the plan to the user. Ask: [A] Start Phase 1 now, [B] Save plan to `docs/04-architecture/migration-<target>.md`, [C] Adjust the scope or approach.
+
+## Output
+
+Migration Plan document with phases, risk assessments, rollback strategies, and effort estimates. Optional: saved to `docs/04-architecture/`. Ready to execute phase by phase.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/migration/skills/agileflow-migration/workflows/validate.md

@@ -0,0 +1,71 @@
+# Validate Workflow — Post-Migration Verification
+
+**Triggers:** "validate the migration", "did the upgrade succeed", "check migration is complete", "run post-migration checks", "verify nothing broke after upgrading"
+
+**Goal:** Run comprehensive checks after a migration — tests, type checking, linting, build, and deprecated API scan — then report PASS / PARTIAL / FAIL with specific issues.
+
+## Inputs needed
+
+| Input  | Required | How to get it                                                   |
+| ------ | -------- | --------------------------------------------------------------- |
+| target | No       | Auto-detect from migration plan or ask: "What did you migrate?" |
+| strict | No       | Default: false. Strict mode = zero warnings tolerance           |
+
+## Steps
+
+1. Identify the migration target. Look for a migration plan file in `docs/04-architecture/migration-*.md`. If not found, ask: "What did you migrate? (e.g., react@18, next@15)"
+
+2. Run all validation checks in sequence (each must pass before reporting):
+
+   | Check           | Command                  | Pass Criteria                           |
+   | --------------- | ------------------------ | --------------------------------------- |
+   | Tests           | `npm test`               | All passing (no regressions)            |
+   | Type check      | `npx tsc --noEmit`       | Zero type errors                        |
+   | Lint            | `npm run lint`           | Zero errors (warnings OK unless strict) |
+   | Build           | `npm run build`          | Exits 0                                 |
+   | Deprecated scan | Re-scan for old patterns | Zero deprecated APIs in migrated areas  |
+
+3. Compare before/after metrics if a migration plan exists:
+   - Test count: same or more (not fewer — regression risk if tests disappeared)
+   - Build size: within 10% (flag large increases)
+   - Type errors: zero new errors
+
+4. Generate the Validation Report:
+
+   ```
+   # Migration Validation Report
+   Generated / Migration / Status: PASS | PARTIAL | FAIL
+
+   ## Check Results
+   | Check | Status | Details |
+   |-------|--------|---------|
+   | Tests | PASS | 247 passing, 0 failing |
+   | Types | PASS | 0 errors |
+   | Lint | WARN | 3 warnings (non-blocking) |
+   | Build | PASS | 2.1MB (+0.3%) |
+   | Deprecated | PASS | 0 remaining |
+
+   ## Issues Found
+   [Only populated if status != PASS]
+   ```
+
+5. Present the report. Ask the user:
+   - If PASS: [A] Merge to main, [B] Create a summary ADR documenting the migration decision
+   - If PARTIAL: [A] Fix the remaining issues (list them with suggested fixes), [B] Accept as-is and document the known issues
+   - If FAIL: [A] Show me what failed and help fix it, [B] Roll back the migration
+
+## Output
+
+Validation report with PASS/PARTIAL/FAIL status for all checks. Specific issue details for any failures. Recommendation on whether to merge or roll back.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/performance/plugin.yaml

@@ -0,0 +1,14 @@
+id: performance
+name: Performance
+description: Profiling and optimization for speed, memory, and Core Web Vitals.
+version: 1.0.0
+enabledByDefault: false
+cannotDisable: false
+depends: []
+provides:
+  skills:
+    - id: agileflow-performance
+      dir: skills/agileflow-performance
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/performance/skills/agileflow-performance/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: agileflow-performance
+version: 1.0.0
+category: agileflow/performance
+description: |
+  Use when a feature, page, or API is too slow, memory usage is growing,
+  bundle size is excessive, or Core Web Vitals need improvement. Applies
+  measure-first discipline: profile before optimizing, benchmark before
+  and after, never optimize without data.
+triggers:
+  keywords:
+    - performance
+    - slow
+    - optimize
+    - bundle size
+    - memory leak
+    - profiling
+    - benchmark
+    - core web vitals
+    - LCP
+    - CLS
+    - INP
+    - FID
+    - lighthouse
+    - query slow
+    - too large
+    - loading time
+    - lag
+    - fps
+    - jank
+  priority: 50
+  exclude:
+    - performance review (HR)
+    - team performance
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/performance.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Performance
+
+Profile first. Optimize second. Benchmark both. This skill applies rigorous measure-first discipline to frontend rendering, backend throughput, database queries, and Core Web Vitals.
+
+## When this skill activates
+
+- A page, API endpoint, or function is noticeably slow or timing out
+- Lighthouse or a monitoring tool flags a failing Core Web Vitals score
+- Memory usage grows over time under steady load (memory leak suspected)
+- Bundle size is bloating CI checks or affecting Time to Interactive
+- A database query is flagged in the slow query log or an APM trace
+- User reports lag, jank, or unresponsive interactions
+
+## The golden rule
+
+**Measure first. Never guess.**
+
+Every optimization must start with a profile, not a hunch. The most common mistake in performance work is optimizing the wrong thing confidently. A 10x speedup on the wrong function saves nothing.
+
+```
+Profile → Identify bottleneck → Form hypothesis → Apply ONE change → Measure again → Document delta
+```
+
+Do not apply multiple changes at once. You will not know which one helped.
+
+## Opening discovery flow
+
+**When invoked without clear context, ask one focused question to understand scope and domain.**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What kind of performance problem are you investigating?",
+    "header": "Performance domain",
+    "multiSelect": false,
+    "options": [
+      {"label": "Frontend — page feels slow or jank (Recommended starting point)", "description": "Bundle size, render performance, Core Web Vitals (LCP, INP, CLS), Time to Interactive"},
+      {"label": "Backend / API — endpoint is slow or timing out", "description": "Request latency, throughput, Node.js/Python/Go profiling, async bottlenecks"},
+      {"label": "Database — queries are slow or causing N+1 problems", "description": "EXPLAIN ANALYZE, missing indexes, N+1 elimination, connection pooling"},
+      {"label": "Memory — usage grows over time (leak suspected)", "description": "Heap snapshots, allocation timelines, finding the retaining reference"},
+      {"label": "Core Web Vitals — Lighthouse / CrUX score failing", "description": "LCP, INP, CLS diagnosis and targeted fixes with field data verification"}
+    ]
+  },
+  {
+    "question": "Do you have profiling data or benchmark numbers already?",
+    "header": "Baseline",
+    "multiSelect": false,
+    "options": [
+      {"label": "No — I need help establishing a baseline first", "description": "I'll walk you through profiling the right layer for your domain"},
+      {"label": "Yes — I have a Lighthouse report / flame chart / slow query log", "description": "Paste or describe it and I'll interpret the data and suggest targeted fixes"},
+      {"label": "Yes — I have before/after numbers and want help interpreting them", "description": "Share the numbers and I'll tell you if the improvement is meaningful and what to try next"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+**Route based on answers:**
+
+| Domain            | Next action                                                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Frontend / bundle | Follow `workflows/profile-and-fix.md` using Chrome DevTools + Lighthouse                                          |
+| Backend / API     | Follow `workflows/profile-and-fix.md` using clinic.js / pprof / py-spy                                            |
+| Database          | Follow `workflows/profile-and-fix.md` using EXPLAIN ANALYZE, then `references/optimization-patterns.md` §Database |
+| Memory            | Load `references/profiling-guide.md` §Memory profiling; follow heap snapshot workflow                             |
+| Core Web Vitals   | Follow `workflows/improve-web-vitals.md`                                                                          |
+
+## Performance budget
+
+Establish a budget before optimizing. Without a target, you will never know when you are done.
+
+| Metric                    | Good       | Needs work     | Poor              |
+| ------------------------- | ---------- | -------------- | ----------------- |
+| LCP                       | < 2.5 s    | 2.5 – 4.0 s    | > 4.0 s           |
+| INP                       | < 200 ms   | 200 – 500 ms   | > 500 ms          |
+| CLS                       | < 0.1      | 0.1 – 0.25     | > 0.25            |
+| TTFB                      | < 800 ms   | 800 ms – 1.8 s | > 1.8 s           |
+| JS bundle (initial, gzip) | < 200 KB   | 200 – 400 KB   | > 400 KB          |
+| API p50 latency           | < 100 ms   | 100 – 500 ms   | > 500 ms          |
+| API p95 latency           | < 500 ms   | 500 ms – 2 s   | > 2 s             |
+| DB query (simple)         | < 10 ms    | 10 – 100 ms    | > 100 ms          |
+| DB query (complex/join)   | < 100 ms   | 100 – 500 ms   | > 500 ms          |
+| Heap growth (steady load) | < 10 MB/hr | 10 – 50 MB/hr  | > 50 MB/hr (leak) |
+
+## The three domains
+
+### Frontend
+
+The browser is a single-threaded environment. Anything that blocks the main thread for more than 50 ms becomes a "long task" and causes jank. The critical insight: **most frontend performance problems are caused by too much JavaScript, not slow JavaScript**.
+
+Primary tools: Chrome DevTools Performance tab, Lighthouse CI, React DevTools Profiler, webpack-bundle-analyzer / vite-bundle-visualizer.
+
+See `references/profiling-guide.md` §Frontend profiling and `references/optimization-patterns.md` §Frontend rendering.
+
+### Backend
+
+Backend performance problems fall into three categories: CPU-bound (computation takes too long), I/O-bound (waiting for DB, network, filesystem), or memory-bound (GC pressure, allocations). The profile will tell you which one before you write a line of optimization code.
+
+Primary tools: clinic.js (Node.js), py-spy / cProfile (Python), pprof (Go), APM traces (Datadog, New Relic, Sentry).
+
+See `references/profiling-guide.md` §Backend profiling and `references/optimization-patterns.md` §Backend.
+
+### Database
+
+The most common database performance problems are: missing index on a filtered/sorted column, N+1 query pattern, SELECT \* where only 2 columns are needed, and offset pagination on large tables. EXPLAIN ANALYZE reveals all of these in seconds.
+
+Primary tools: EXPLAIN ANALYZE (PostgreSQL), EXPLAIN FORMAT=JSON (MySQL), slow query log, pg_stat_statements.
+
+See `references/profiling-guide.md` §Backend profiling §Database and `references/optimization-patterns.md` §Database.
+
+## Anti-patterns
+
+| Anti-pattern                        | Why it is harmful                                                                                     |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Premature optimization              | Wastes time on code that isn't the bottleneck; makes code harder to read without measurable benefit   |
+| Optimizing without a baseline       | You cannot know if a change helped without a before number                                            |
+| Applying multiple changes at once   | You cannot attribute the improvement to the right change                                              |
+| Optimizing in production under load | Confounds profiling results; always profile in a representative but controlled environment            |
+| Micro-benchmarking in isolation     | A function that runs in 1 µs in isolation may dominate wall time when called 10,000 times per request |
+| Caching as the first response       | Caches hide bugs and make correctness harder to verify; optimize the source query first               |
+| Ignoring field data (CrUX)          | Lab metrics (Lighthouse) can look great while real-user experience is poor due to device/network mix  |
+
+## Self-improving learnings
+
+`_learnings/performance.yaml` records:
+
+- The primary tech stack (React, Next.js, Express, Django, Go, PostgreSQL, etc.)
+- Performance budgets agreed for this project
+- Profiling tools already installed and configured
+- Known bottlenecks previously resolved (avoid re-investigating)
+- Team preferences: APM tool, benchmark runner, browser target
+
+Apply on invocation; update on correction.
+
+## Quality checklist
+
+Before delivering any optimization:
+
+- [ ] Baseline measured before any change (numbers, not impressions)
+- [ ] Only one change applied at a time between measurements
+- [ ] After-change measurement taken in the same environment as baseline
+- [ ] Improvement is statistically meaningful (not within noise margin)
+- [ ] No regression introduced in other metrics (check LCP if optimizing CLS, etc.)
+- [ ] Optimization does not break correctness (tests still pass)
+- [ ] Change is documented with before/after numbers and rationale
+- [ ] Performance budget updated if targets have shifted
+
+## Integration
+
+- **agileflow-test-writer** — write benchmark and load tests to lock in performance gains; a gain without a test can silently regress
+- **agileflow-adr** — document architecture decisions made in the name of performance (caching layer, CDN, query redesign, data structure changes)
+- **agileflow-pr-reviewer** — code review after optimisation to confirm correctness and readability are preserved alongside the performance improvement
+- **agileflow-database** — query performance, index analysis, and connection pooling overlap; coordinate for storage-layer bottlenecks (N+1 queries, missing indexes)
+- **agileflow-engineering** — delegate implementation of performance fixes (memoisation, code splitting, lazy loading, worker threads) to engineering
+- **agileflow-refactor** — when performance problems stem from structural issues (deep coupling, repeated computation), pair with refactor to fix the root cause cleanly
+- **agileflow-audit** — the performance dimension of the full audit surfaces bundle size, render, query, and asset issues; performance fixes what audit finds
+- **agileflow-debug** — use debug when a performance regression appears suddenly and the cause is unclear; systematic root cause analysis before optimising
+- **agileflow-seo** — Core Web Vitals (LCP, INP, CLS) directly affect search rankings; performance improvements here feed directly into SEO gains
+- **agileflow-delivery** — include a performance budget check as a delivery gate for any feature touching render paths or large data payloads
+
+## References
+
+Load these files when you need deeper context:
+
+| File                                  | When to load                                                                              |
+| ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `references/profiling-guide.md`       | Choosing profiling tools, reading flame charts, taking heap snapshots, APM interpretation |
+| `references/optimization-patterns.md` | Concrete techniques for frontend rendering, backend throughput, and database queries      |
+| `references/web-vitals-guide.md`      | LCP, INP, CLS deep reference — diagnosis, causes, and targeted fixes                      |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                              | When to follow                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------- |
+| `workflows/profile-and-fix.md`    | User has a slow feature, API, query, or memory problem and needs a structured investigation |
+| `workflows/improve-web-vitals.md` | User has a failing Core Web Vitals score and needs targeted improvements                    |