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

package/content/plugins/seo/skills/agileflow-seo/workflows/page.md

@@ -0,0 +1,118 @@
+# Page Workflow — Single Page SEO Analysis
+
+**Triggers:** "analyze this page for SEO", "check the SEO on /about", "deep SEO analysis for this URL", "is this page optimized", "on-page SEO for example.com/product", "why isn't this page ranking"
+
+**Goal:** Deep, scored analysis of a single page across 6 SEO dimensions — produces a report card with specific, copy-paste-ready fixes ordered by impact.
+
+## Inputs needed
+
+| Input          | Required | How to get it                                                                                                 |
+| -------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| URL            | Yes      | Ask for it if not provided                                                                                    |
+| target keyword | No       | Ask: "What keyword are you trying to rank this page for?" — changes relevance scoring                         |
+| context        | No       | "Why are you analyzing this page?" — surfaces whether it's a ranking drop, pre-launch review, or optimization |
+
+## Steps
+
+1. **If URL is not provided**, ask: _"Which page URL should I analyze?"_ If they say the page isn't ranking, also ask: _"What keyword are you trying to rank it for?"_ — this context changes every recommendation.
+
+2. **Fetch the page.** Check HTTP status, response time, HTTPS. Extract full HTML. If the page returns non-200, diagnose the status code issue before proceeding.
+
+3. **Analyze all 6 dimensions:**
+
+   **On-Page SEO**
+   - Title tag: present? 30–60 chars? keyword-forward? unique?
+   - Meta description: present? 120–160 chars? has CTA?
+   - H1: exactly 1? contains target keyword?
+   - H2–H6: logical hierarchy, no skipped levels?
+   - Internal links: 2–10 per page, descriptive anchors?
+   - URL: clean, short, keyword-relevant?
+   - Canonical: self-referencing or correct target?
+   - Open Graph: og:title, og:description, og:image all present?
+
+   **Content Quality**
+   - Word count vs page type minimum (homepage: 300+, blog: 800+, product: 500+)
+   - Content uniqueness — not boilerplate
+   - Readability level appropriate for audience
+   - E-E-A-T signals: author attribution, expertise indicators, trust signals
+   - AI citation readiness: 134–167 word structured blocks
+
+   **Technical**
+   - HTTP status code and response time / TTFB
+   - Mobile viewport configured
+   - Robots directives (index/noindex)
+   - Structured data presence
+
+   **Schema Markup**
+   - Correct schema type for page content
+   - Required properties present
+   - No validation errors
+   - Matches visible page content
+
+   **Images**
+   - Alt text present on all meaningful images
+   - File sizes reasonable (< 200KB for hero images)
+   - Next-gen formats (WebP/AVIF)
+   - Lazy loading on below-fold images
+   - Responsive image attributes
+
+   **Performance**
+   - Core Web Vitals indicators from page source
+   - Render-blocking resources
+   - Unminified JS/CSS
+   - Missing compression signals
+
+4. **Score each dimension 0–100.** Thresholds: 90+ excellent, 75–89 good, 60–74 needs work, below 60 critical.
+
+5. **Present the report card:**
+
+   ```
+   Page: example.com/pricing
+   Target keyword: project management software
+
+   Dimension       Score   Top Issue
+   On-Page SEO     84      H1 missing target keyword
+   Content         71      Word count below minimum (320 vs 800+)
+   Technical       95      —
+   Schema          45      Product schema missing price property
+   Images          60      6 images missing alt text
+   Performance     78      Render-blocking CSS (2 files)
+
+   Overall: 72/100
+   ```
+
+6. **List specific fixes ordered by impact** — critical issues first, then quick wins, then fine-tuning. For each fix, include the exact change needed (not just "fix the H1" — say "Change H1 from 'Our Pricing Plans' to 'Project Management Software — Pricing'").
+
+7. **Guide next step with AskUserQuestion:**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "{page} scored {X}/100. {top_issue} is the biggest drag. Here's what to fix first:",
+  "header": "Next action",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix {top_issue} now (Recommended)", "description": "{exact change needed + expected impact}"},
+    {"label": "Generate {missing_schema_type} schema for this page", "description": "I'll produce ready-to-use JSON-LD — copy it into your <head>"},
+    {"label": "Compare this page against a ranking competitor", "description": "Find a competitor ranking for {target_keyword} — I'll show you the gap"},
+    {"label": "Run full site audit to see site-wide patterns", "description": "Check if these issues affect other pages too — full health score for the whole domain"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+## Output
+
+Per-dimension scores (0–100) with specific findings. Prioritized fix list with exact changes. Overall page score. If target keyword was provided, keyword-specific recommendations.
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+Present options as a numbered list. Example:
+
+```
+What would you like to do next?
+1. Fix the top issue now
+2. Generate schema markup for this page
+3. Run a full site audit
+```

package/content/plugins/testing/plugin.yaml

@@ -0,0 +1,16 @@
+id: testing
+name: Testing
+description: Write comprehensive test suites from acceptance criteria and increase code coverage.
+version: 1.0.0
+enabledByDefault: false
+cannotDisable: false
+
+depends: []
+
+provides:
+  skills:
+    - id: agileflow-test-writer
+      dir: skills/agileflow-test-writer
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/testing/skills/agileflow-test-writer/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: agileflow-test-writer
+version: 1.0.0
+category: agileflow/testing
+description: |
+  Use when the user wants to write tests for new or existing code.
+  Generates comprehensive test suites from acceptance criteria, covers
+  happy paths, sad paths, and edge cases, and selects the right
+  framework for the codebase. Also increases coverage on existing code
+  that lacks tests.
+triggers:
+  keywords:
+    - write tests
+    - add tests
+    - test this
+    - unit test
+    - integration test
+    - test coverage
+    - missing tests
+    - tests for
+    - spec file
+    - test suite
+    - tdd
+    - test-driven
+    - testing
+  priority: 50
+  exclude:
+    - test environment (infrastructure context)
+    - user acceptance testing (UAT project management)
+    - penetration testing
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/test-writer.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Test Writer
+
+Turns acceptance criteria and existing code into complete, well-structured test suites — with happy paths, sad paths, edge cases, and the right mocking strategy for the codebase.
+
+## When this skill activates
+
+- User asks to write, add, or generate tests for a feature, function, or module
+- User references a user story and wants tests derived from its AC
+- User wants to increase test coverage on a file or directory
+- User is practicing TDD and needs a failing test written before the implementation
+- User mentions a specific test framework (Jest, Vitest, pytest, RSpec, Go test) and wants help
+
+## Opening discovery flow
+
+**When invoked without clear context, ask one focused question to understand scope and framework.**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What would you like to test?",
+    "header": "Test scope",
+    "multiSelect": false,
+    "options": [
+      {"label": "Write tests from a user story or acceptance criteria (Recommended)", "description": "Paste your story or AC and I'll derive a complete test plan — happy paths, sad paths, edge cases"},
+      {"label": "Add tests to existing code with low or no coverage", "description": "Point me at a file or module and I'll analyse what's untested and write the missing tests"},
+      {"label": "Write tests first (TDD) — implementation comes after", "description": "Describe the behaviour you want and I'll write the failing tests before you write a single line of production code"},
+      {"label": "Write an integration test for a specific flow", "description": "e.g. API endpoint, database round-trip, UI interaction — I'll choose the right layer and tooling"},
+      {"label": "Improve a specific existing test file", "description": "Paste the test file; I'll find gaps, weak assertions, missing edge cases, and brittle mocks"}
+    ]
+  },
+  {
+    "question": "Which test framework does this project use?",
+    "header": "Framework",
+    "multiSelect": false,
+    "options": [
+      {"label": "Vitest (Recommended for Vite/React projects)", "description": "ESM-native, fast, Jest-compatible API"},
+      {"label": "Jest", "description": "Most common Node.js test runner — CommonJS or ESM"},
+      {"label": "pytest", "description": "Python — fixtures, parametrize, and rich plugin ecosystem"},
+      {"label": "Go test (testing package)", "description": "Table-driven tests, subtests, benchmarks"},
+      {"label": "RSpec", "description": "Ruby — describe/context/it, let, before hooks"},
+      {"label": "Not sure — detect it for me", "description": "I'll read package.json / requirements.txt / go.mod to figure it out"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+**Route based on answers:**
+
+| Scope                 | Next action                                                                        |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| From AC / story       | Follow `workflows/write-tests-from-ac.md`                                          |
+| Add coverage          | Follow `workflows/add-coverage.md`                                                 |
+| TDD                   | Write the failing tests, then offer to stub the implementation                     |
+| Integration test      | Ask for the endpoint/flow details; choose layer from `references/test-patterns.md` |
+| Improve existing file | Read the file, run gap analysis, present findings first                            |
+
+## What makes a great test suite
+
+### The test pyramid
+
+```
+        /\
+       /E2E\          ← few, slow, high-confidence
+      /------\
+     /Integr. \       ← moderate, tests wiring
+    /----------\
+   /   Unit    \      ← many, fast, isolated
+  /____________\
+```
+
+Each layer has a job. Don't try to do everything at one layer.
+
+| Layer        | Purpose                                         | Speed    | Isolation                    |
+| ------------ | ----------------------------------------------- | -------- | ---------------------------- |
+| Unit         | Test one function or class in isolation         | < 1ms    | Full mocks/stubs             |
+| Integration  | Test two or more real components wired together | 10–500ms | DB, real modules, no network |
+| E2E / System | Test the whole system from the outside          | Seconds  | Real browser / HTTP          |
+
+### The four-phase test structure
+
+Every test should follow: **Arrange → Act → Assert → (Cleanup)**
+
+```js
+// Arrange
+const user = createUser({ role: "admin" });
+const service = new UserService({ db: mockDb });
+
+// Act
+const result = await service.delete(user.id);
+
+// Assert
+expect(result.success).toBe(true);
+expect(mockDb.delete).toHaveBeenCalledWith("users", user.id);
+```
+
+### Happy / sad / edge coverage
+
+For every acceptance criterion, derive three test categories:
+
+| Category       | Description                                    | Example                                                |
+| -------------- | ---------------------------------------------- | ------------------------------------------------------ |
+| **Happy path** | The criterion succeeds under normal conditions | Valid input, user is authenticated, data exists        |
+| **Sad path**   | The criterion fails gracefully                 | Invalid input, unauthorized, resource not found        |
+| **Edge case**  | Boundary conditions and unusual inputs         | Empty string, zero, null, max-length, concurrent calls |
+
+## Framework selection guide
+
+| Signal                                     | Recommended framework |
+| ------------------------------------------ | --------------------- |
+| `package.json` contains `vite` or `vitest` | Vitest                |
+| `package.json` contains `jest`             | Jest                  |
+| `*.py` source files                        | pytest                |
+| `go.mod` present                           | Go test               |
+| `Gemfile` with `rspec`                     | RSpec                 |
+| `.NET` / `*.csproj`                        | xUnit or NUnit        |
+| Unknown — ask                              | Ask the user          |
+
+## Mocking strategy
+
+**Mock at the boundary, not inside the unit.**
+
+- Mock: external HTTP calls, databases, file system, time (`Date.now`), randomness
+- Don't mock: the module under test, pure functions, domain logic
+
+```js
+// Good — mock the HTTP boundary
+vi.mock("./api-client", () => ({
+  fetchUser: vi.fn().mockResolvedValue({ id: 1, name: "Alice" }),
+}));
+
+// Bad — mocking the thing you're testing
+vi.mock("./user-service"); // ← this tests nothing
+```
+
+**Prefer fakes over mocks when the interface is stable:**
+
+- A fake in-memory database is more robust than 40 `mockResolvedValue` calls
+- Fakes exercise real behaviour; mocks only verify calls were made
+
+## Coverage targets
+
+See `references/coverage-targets.md` for the full coverage guide. Quick reference:
+
+| Project maturity            | Line coverage target           |
+| --------------------------- | ------------------------------ |
+| Greenfield / critical path  | 90%+                           |
+| Established with some tests | 70–80%                         |
+| Legacy brownfield           | 40–60% (improve incrementally) |
+| UI/presentation layer       | 60% (unit) + visual regression |
+
+Coverage is a floor, not a goal. 80% coverage with weak assertions is worse than 60% coverage with strong assertions. Always prioritise assertion quality over line count.
+
+## Self-improving learnings
+
+`_learnings/test-writer.yaml` records:
+
+- Preferred test framework and version
+- Coverage thresholds the team uses
+- Mocking library preference (vi.mock, jest.mock, sinon, unittest.mock)
+- Whether the project uses factories/fixtures for test data
+- Naming conventions for test files (`*.test.ts` vs `*.spec.ts`)
+- Whether the team prefers `describe/it` or flat test functions
+
+Apply on invocation; update on correction.
+
+## Output format
+
+When writing tests, always:
+
+1. Start with a brief comment block explaining what is being tested and why
+2. Group tests with `describe` blocks by feature / scenario
+3. Use descriptive `it`/`test` names: `it('returns 404 when user does not exist')`
+4. Include at least one assertion per test; prefer `toEqual` over `toBeTruthy` for clarity
+5. End with a coverage summary: which lines/branches are now covered
+
+## Quality checklist
+
+Before delivering a test suite:
+
+- [ ] At least one happy-path test per acceptance criterion
+- [ ] At least one sad-path test per acceptance criterion
+- [ ] Edge cases for every input that accepts strings, numbers, or arrays
+- [ ] All external dependencies mocked at the correct boundary
+- [ ] No test depends on another test's state
+- [ ] Test names read as documentation
+- [ ] Tests can be run in any order and pass consistently (no flakiness)
+- [ ] Tests are in the correct layer (unit vs integration vs e2e)
+
+## Integration
+
+- **agileflow-story-writer** — provides the source acceptance criteria; test-writer maps each AC to one or more test cases and coverage type
+- **agileflow-pr-reviewer** — checks test coverage as part of PR review; test-writer is invoked when the reviewer flags missing coverage
+- **agileflow-refactor** — refactored code must have its tests updated in the same pass; spawn test-writer before a refactor begins to ensure the safety net exists
+- **agileflow-engineering** — spawn test-writer after implementation completes to cover the new code with unit, integration, and E2E tests
+- **agileflow-debug** — after a bug is fixed, spawn test-writer to add a regression test that prevents it from returning; the fix isn't done without the test
+- **agileflow-accessibility** — generate axe-core and keyboard navigation tests alongside functional tests for any UI story
+- **agileflow-performance** — generate benchmark tests to lock in performance gains; test-writer provides the measurement harness, performance provides the thresholds
+- **agileflow-database** — generate migration validation tests and repository-layer integration tests that hit a real database, not mocks
+- **agileflow-delivery** — test-writer is a delivery gate; delivery should confirm coverage thresholds are met before shipping
+
+## References
+
+Load these files when you need deeper context:
+
+| File                             | When to load                                                                                |
+| -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `references/test-patterns.md`    | Choosing the right test structure by layer, framework-specific patterns, mocking strategies |
+| `references/coverage-targets.md` | Understanding coverage targets by project type and how to prioritise what to test first     |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                               | When to follow                                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------------- |
+| `workflows/write-tests-from-ac.md` | User has acceptance criteria or a user story and wants a test suite generated from it |
+| `workflows/add-coverage.md`        | User wants to increase test coverage for existing code that is undertested            |

package/content/plugins/testing/skills/agileflow-test-writer/references/coverage-targets.md

@@ -0,0 +1,239 @@
+# Coverage Targets Reference
+
+**Load this when:** setting or evaluating coverage thresholds, prioritising which code to test first, or explaining coverage concepts to the team.
+
+---
+
+## Coverage is a floor, not a goal
+
+A test suite with 95% line coverage and weak assertions (`toBeTruthy`, `toBeDefined`) gives false confidence. Coverage measures which lines of code were _executed_ by tests — not whether those tests _verify_ anything useful.
+
+**Rule of thumb:** 70% coverage with strong assertions beats 95% coverage with trivial assertions.
+
+---
+
+## Coverage types explained
+
+| Type                   | What it measures                | How hard to achieve | Recommended?                        |
+| ---------------------- | ------------------------------- | ------------------- | ----------------------------------- |
+| **Line coverage**      | Was each line executed?         | Easiest             | Use as baseline metric              |
+| **Branch coverage**    | Was each if/else branch taken?  | Medium              | More meaningful than line; use this |
+| **Function coverage**  | Was each function called?       | Easy                | Good sanity check                   |
+| **Statement coverage** | Was each statement executed?    | Similar to line     | Use when line coverage unavailable  |
+| **Mutation testing**   | Do tests catch deliberate bugs? | Hardest             | Best signal of test quality         |
+
+**Recommended combination:** Track branch coverage as your primary metric + function coverage as a quick sanity check. Line coverage is fine as a secondary metric.
+
+---
+
+## Coverage targets by project type
+
+### Greenfield / new features
+
+| Layer                         | Branch coverage target | Rationale                               |
+| ----------------------------- | ---------------------- | --------------------------------------- |
+| Domain logic / business rules | 95%+                   | Bugs here are expensive                 |
+| API handlers / controllers    | 90%+                   | All status codes + error paths          |
+| Data access / repositories    | 85%+                   | All query paths including empty results |
+| Utilities / helpers           | 90%+                   | Pure functions — easy and high-value    |
+| UI components (unit)          | 70%+                   | Focus on behaviour, not render output   |
+| Configuration / bootstrap     | 50%+                   | Often hard to test; smoke tests suffice |
+
+### Established codebase
+
+| Layer         | Branch coverage target |
+| ------------- | ---------------------- |
+| Domain logic  | 85%+                   |
+| API handlers  | 80%+                   |
+| Data access   | 75%+                   |
+| Utilities     | 85%+                   |
+| UI components | 60%+                   |
+
+### Legacy / brownfield (incremental improvement)
+
+Do NOT set a global target on a legacy codebase — it creates perverse incentives (trivial tests to hit a number). Instead:
+
+1. **Protect the happy path** — write integration tests for critical flows first
+2. **Test before refactoring** — add tests whenever you touch a file
+3. **Ratchet coverage up** — never reduce coverage; gate PRs on "no regression"
+4. **Prioritise by risk** — payment flows, auth, data mutations before UI
+
+---
+
+## What NOT to test
+
+Do not write tests for code that:
+
+| Category                                          | Why                                                       |
+| ------------------------------------------------- | --------------------------------------------------------- |
+| Auto-generated code (migrations, generated types) | Code is not hand-authored; tests would test the generator |
+| Configuration constants (colours, strings)        | No logic to verify                                        |
+| Framework boilerplate (e.g. `app.listen(3000)`)   | Framework is already tested                               |
+| Third-party library internals                     | Not your responsibility                                   |
+| Trivial getters/setters with no logic             | Zero ROI                                                  |
+| Test helpers themselves                           | Usually overkill; only test helpers if they are complex   |
+
+Exclude these from coverage reporting in vitest.config.ts / jest.config.js:
+
+```js
+// vitest.config.ts
+export default {
+  test: {
+    coverage: {
+      exclude: [
+        "src/generated/**",
+        "src/config/constants.ts",
+        "**/*.d.ts",
+        "**/index.ts", // barrel files — no logic
+      ],
+    },
+  },
+};
+```
+
+---
+
+## Coverage tooling setup
+
+### Vitest
+
+```js
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: "v8", // or 'istanbul'
+      reporter: ["text", "lcov", "html"],
+      thresholds: {
+        branches: 80,
+        functions: 85,
+        lines: 85,
+        statements: 85,
+      },
+      include: ["src/**/*.{ts,js}"],
+      exclude: ["src/**/*.test.{ts,js}", "src/generated/**"],
+    },
+  },
+});
+```
+
+Run: `npx vitest run --coverage`
+
+### Jest
+
+```js
+// jest.config.js
+module.exports = {
+  collectCoverage: true,
+  coverageProvider: "v8",
+  coverageReporters: ["text", "lcov", "html"],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 85,
+      lines: 85,
+      statements: 85,
+    },
+  },
+  collectCoverageFrom: [
+    "src/**/*.{js,ts}",
+    "!src/**/*.test.{js,ts}",
+    "!src/generated/**",
+  ],
+};
+```
+
+Run: `npx jest --coverage`
+
+### pytest + pytest-cov
+
+```ini
+# pytest.ini or pyproject.toml [tool.pytest.ini_options]
+addopts = --cov=src --cov-report=term-missing --cov-report=html --cov-fail-under=80
+```
+
+Run: `pytest --cov`
+
+### Go
+
+```bash
+go test ./... -coverprofile=coverage.out
+go tool cover -html=coverage.out   # visual report
+go tool cover -func=coverage.out   # per-function summary
+```
+
+---
+
+## Prioritising what to test first
+
+When coverage is low and you need to decide where to start, use this priority order:
+
+### Priority 1: Critical paths (always test these)
+
+- Authentication and authorisation checks
+- Payment processing and financial calculations
+- Data mutations that cannot be undone (delete, archive)
+- External API integrations (mock the external call, test the adapter logic)
+- Security-sensitive operations (password hashing, token generation, input sanitisation)
+
+### Priority 2: High-value business logic
+
+- Core domain rules (pricing, eligibility, routing)
+- Complex state machines
+- Data transformations used in multiple places
+
+### Priority 3: Error handling
+
+- What happens when a dependency returns an error?
+- What happens when input is malformed?
+- Does the system degrade gracefully?
+
+### Priority 4: Happy paths on remaining features
+
+Fill in coverage on everything else after the above are covered.
+
+---
+
+## Interpreting a coverage report
+
+When reading a coverage report, look for:
+
+| Signal                        | What it means                                                                                       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------- |
+| Branch < 60% on a domain file | Probably missing sad-path tests                                                                     |
+| Function < 70%                | Untested functions — dead code or missing tests                                                     |
+| A file at exactly 100%        | Usually means tests were written to cover lines, not to verify behaviour — review assertion quality |
+| Large file with 0%            | Either dead code (delete it) or a critical gap                                                      |
+
+---
+
+## Coverage in CI
+
+Add coverage checks to CI to prevent regressions:
+
+```yaml
+# GitHub Actions example
+- name: Test with coverage
+  run: npx vitest run --coverage
+
+- name: Upload coverage report
+  uses: codecov/codecov-action@v4
+  with:
+    files: ./coverage/lcov.info
+```
+
+**Gate strategy:** Fail the build if coverage drops below threshold (use `coverageThreshold` in config). Don't require 100% — that creates perverse incentives.
+
+---
+
+## Common coverage anti-patterns
+
+| Anti-pattern                                         | Problem                                                         |
+| ---------------------------------------------------- | --------------------------------------------------------------- |
+| Writing tests just to hit the threshold              | Results in trivial tests; wastes time; creates false confidence |
+| 100% coverage as a team rule                         | Forces tests on trivial getters; makes adding code painful      |
+| Testing the test setup (testing mock calls directly) | Proves the mock works, not the production code                  |
+| No coverage check in CI                              | Coverage regresses silently over time                           |
+| Excluding too much from coverage                     | Hides real gaps; start conservative with exclusions             |