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

package/content/plugins/delivery/plugin.yaml

@@ -0,0 +1,19 @@
+id: delivery
+name: Delivery
+description: Delivery workflow skill pack.
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  skills:
+    - id: agileflow-delivery
+      dir: skills/agileflow-delivery
+  agents:
+    - id: ci
+      path: agents/ci.md
+    - id: devops
+      path: agents/devops.md
+  hooks: []
+  templates: []

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

@@ -0,0 +1,111 @@
+---
+name: agileflow-delivery
+version: 1.0.0
+category: agileflow/delivery
+description: |
+  Use when the user is preparing to ship: creating a PR, running CI,
+  managing dependencies, generating a changelog, planning a sprint,
+  or setting up deployment. Covers the full delivery pipeline from
+  PR description to production.
+triggers:
+  keywords:
+    - create pr
+    - pull request
+    - ship it
+    - deploy
+    - ci pipeline
+    - changelog
+    - release
+    - dependencies
+    - sprint planning
+    - ready to merge
+    - npm audit
+    - dependency update
+  priority: 55
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/delivery.yaml
+  maxEntries: 30
+depends:
+  skills: []
+  plugins: [delivery]
+---
+
+# AgileFlow Delivery
+
+End-of-story delivery toolkit: write the PR, run CI, check dependencies,
+generate changelog entries, plan sprints, and coordinate deployment.
+
+## When this skill activates
+
+- User says "create a PR", "ship it", or "ready to merge"
+- User asks about CI failures or deployment setup
+- User wants a changelog entry or release notes
+- User needs dependency auditing or updates
+- User is planning a sprint or tracking velocity
+
+## Capabilities
+
+| Command                | What it does                                         |
+| ---------------------- | ---------------------------------------------------- |
+| `/agileflow:pr`        | Write PR title, summary, and test plan from git diff |
+| `/agileflow:ci`        | Set up or fix CI workflows                           |
+| `/agileflow:deploy`    | Deployment guide and checklist                       |
+| `/agileflow:changelog` | Generate changelog entry from commits                |
+| `/agileflow:deps`      | Dependency audit and update recommendations          |
+| `/agileflow:packages`  | Package management and version pinning               |
+| `/agileflow:sprint`    | Sprint planning and story point estimation           |
+| `/agileflow:devops`    | DevOps automation and infrastructure                 |
+
+## PR workflow
+
+1. Confirm tests pass and AC verified before opening PR
+2. Run `/agileflow:pr` — it reads git diff and generates title + body
+3. Check: does the PR description explain the WHY, not just the WHAT?
+4. Include test plan checklist in the PR body
+
+## Delivery checklist
+
+```
+⬜ Tests passing
+⬜ AC verified
+⬜ Logic audit clean (or findings accepted)
+⬜ PR description written
+⬜ CI green
+⬜ Dependencies up to date
+```
+
+## Integration
+
+- **agileflow-pr-reviewer** — invoke before creating the PR; delivery orchestrates the end-to-end release, pr-reviewer handles the code quality gate within it
+- **agileflow-audit** — run a quick audit sweep before shipping; P0/P1 findings should block the release
+- **agileflow-test-writer** — ensure test coverage meets the threshold before delivery starts; delegate missing tests here
+- **agileflow-accessibility** — run accessibility checks before any user-facing release; required for UI stories
+- **agileflow-docs** — sync documentation as part of the delivery flow; API changes require docs update before or alongside release
+- **agileflow-status-updater** — flip story and epic statuses to done as delivery completes each unit of work
+- **agileflow-seo** — check SEO impact before releasing public-facing page changes, especially new routes or content restructuring
+- **agileflow-ads** — coordinate ad campaign launch with product delivery when releasing a feature tied to a campaign
+- **agileflow-planning** — use for sprint finalisation and velocity capture after a delivery cycle completes
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                                   | When to load                                                                              |
+| -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `references/pr-checklist-guide.md`     | Creating or reviewing a PR — size guidelines, merge strategies, pre-merge checklist       |
+| `references/changelog-format-guide.md` | Writing a changelog entry or release notes — Keep a Changelog format, good vs bad entries |
+| `references/ci-pipeline-guide.md`      | Setting up or debugging a CI pipeline — stages, caching, parallelization strategies       |
+| `references/release-checklist.md`      | Preparing a release — pre/post release gates, rollback triggers, communication templates  |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                     | When to follow                                                                          |
+| ------------------------ | --------------------------------------------------------------------------------------- |
+| `workflows/pr.md`        | User wants to create a pull request — gathers diff, writes title and body, checks gates |
+| `workflows/changelog.md` | User wants to generate a changelog entry from recent commits                            |
+| `workflows/deploy.md`    | User is deploying — environment checks, deploy steps, post-deploy verification          |

package/content/plugins/delivery/skills/agileflow-delivery/references/changelog-format-guide.md

@@ -0,0 +1,133 @@
+# Changelog Format Guide
+
+**Load this when:** generating a CHANGELOG entry, writing release notes,
+or deciding what level of detail to include for a given change type.
+
+## Keep a Changelog format
+
+Standard format (keepachangelog.com):
+
+```markdown
+## [2.4.0] - 2026-03-15
+
+### Added
+
+- Webhook delivery for Slack and Discord notifications
+- Retry queue with exponential backoff (up to 5 attempts)
+- Delivery status dashboard showing per-channel success rates
+
+### Changed
+
+- Queue processing moved to background worker (was inline)
+- Default retry delay increased from 30s to 60s
+
+### Fixed
+
+- Duplicate delivery when network timeout occurred during ACK
+- Missing `Content-Type` header on webhook payloads
+
+### Deprecated
+
+- `deliverSync()` — use `deliver()` with `await` instead
+
+### Removed
+
+- Legacy `v1/webhook` endpoint (deprecated in 2.0.0)
+
+### Security
+
+- Webhook signatures now use HMAC-SHA256 (was MD5)
+```
+
+## Change type guide
+
+| Type           | What belongs here             | Examples                                              |
+| -------------- | ----------------------------- | ----------------------------------------------------- |
+| **Added**      | New features users can use    | New endpoint, new config option, new UI page          |
+| **Changed**    | Behavior that changed         | Different default, renamed field, new required param  |
+| **Fixed**      | Bug fixes                     | Crash fix, wrong output corrected, data integrity fix |
+| **Deprecated** | Will be removed in next major | Old API method, config key, endpoint                  |
+| **Removed**    | Gone in this version          | Deprecated things now deleted                         |
+| **Security**   | Vulnerability fixes           | CVE patches, auth fixes, crypto upgrades              |
+
+**Not in changelog:** Internal refactors, test additions, CI changes, dependency bumps (unless security).
+
+## Writing good changelog entries
+
+**Bad:**
+
+- "Fixed bug"
+- "Updated dependencies"
+- "Improved performance"
+- "Various fixes"
+
+**Good:**
+
+- "Fixed duplicate webhook delivery when network timeout occurred during ACK"
+- "Bumped express to 4.21.0 (resolves CVE-2024-29041)"
+- "Reduced image resize time by 40% by switching to sharp (was jimp)"
+- "Fixed login redirect loop when `returnUrl` contained encoded slashes"
+
+**Rule:** Every entry should answer "what changed and why does it matter to me?"
+
+## Semantic versioning alignment
+
+| Version bump      | When             | What to include                         |
+| ----------------- | ---------------- | --------------------------------------- |
+| **Major** (X.0.0) | Breaking changes | All breaking changes clearly called out |
+| **Minor** (x.Y.0) | New features     | Added section, plus any fixes           |
+| **Patch** (x.y.Z) | Bug fixes only   | Fixed section, security if applicable   |
+
+## Release notes vs changelog
+
+| Format         | Audience   | Tone                      | Length          |
+| -------------- | ---------- | ------------------------- | --------------- |
+| Changelog      | Developers | Technical, precise        | Comprehensive   |
+| Release notes  | All users  | Friendly, benefit-focused | Highlights only |
+| GitHub release | Mixed      | Semi-technical            | Medium          |
+
+### Converting changelog to release notes
+
+Take the changelog entry and:
+
+1. Lead with the most impactful changes
+2. Translate technical details to user benefits
+3. Add upgrade instructions if breaking changes exist
+4. Link to migration guide if needed
+
+```markdown
+# 2.4.0 — Slack & Discord Notifications
+
+You can now deliver to Slack and Discord directly from your workflow.
+Set up a webhook URL in Settings → Integrations and start receiving
+notifications in your channels.
+
+**Other improvements:**
+
+- Delivery reliability improved — retries now use exponential backoff
+- Fixed a rare case where messages could be delivered twice
+
+**Breaking change:** If you use `deliverSync()`, switch to `await deliver()` before upgrading.
+See the [migration guide](link) for details.
+```
+
+## Automating changelog from commits
+
+Conventional commits map to changelog sections:
+
+```
+feat:     → Added
+fix:      → Fixed
+BREAKING: → Changed (with ⚠️ breaking note)
+perf:     → Changed
+refactor: → (skip — internal)
+test:     → (skip — internal)
+chore:    → (skip — unless security)
+docs:     → (skip — unless user-facing docs changed)
+```
+
+### Using git log to draft entries
+
+```bash
+git log v2.3.0..HEAD --oneline --no-merges | grep -E "^[a-f0-9]+ (feat|fix|perf):"
+```

package/content/plugins/delivery/skills/agileflow-delivery/references/ci-pipeline-guide.md

@@ -0,0 +1,158 @@
+# CI Pipeline Guide
+
+**Load this when:** Designing, reviewing, or optimizing a CI/CD pipeline — stages, caching, parallelization, or failure handling.
+
+## Standard Pipeline Stages
+
+```
+trigger → install → lint/typecheck → test → build → security → deploy-staging → smoke-test → deploy-prod
+```
+
+| Stage             | Purpose                 | Fail behavior     | Typical duration |
+| ----------------- | ----------------------- | ----------------- | ---------------- |
+| Install           | Restore deps            | Block all         | 30–90s (cached)  |
+| Lint + typecheck  | Code quality gate       | Block             | 15–60s           |
+| Unit tests        | Fast correctness check  | Block             | 30s–3min         |
+| Integration tests | Service boundary check  | Block             | 1–5min           |
+| Build             | Produce artifact        | Block             | 30s–5min         |
+| Security scan     | CVE + secrets detection | Block on critical | 30s–2min         |
+| Deploy staging    | Validate in env         | Block prod        | 1–3min           |
+| Smoke test        | Critical path check     | Block prod        | 30s–2min         |
+| Deploy prod       | Release                 | —                 | 1–5min           |
+
+---
+
+## Parallelization Strategies
+
+### Run in parallel (no dependencies between each other)
+
+```yaml
+# GitHub Actions example
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps: [...]
+  typecheck:
+    runs-on: ubuntu-latest
+    steps: [...]
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps: [...]
+  # All three run simultaneously
+```
+
+### Matrix strategy (test multiple versions)
+
+```yaml
+strategy:
+  matrix:
+    node: [20, 22]
+    os: [ubuntu-latest, windows-latest]
+```
+
+### Test splitting (large test suites)
+
+- Split by file count across N runners
+- Tools: `jest --shard=1/4`, Vitest `--reporter=verbose`, Playwright sharding
+- Target: each shard under 3 minutes
+
+---
+
+## Caching Reference
+
+### Node.js (npm)
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-npm-
+```
+
+### Node.js (pnpm)
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    cache: "pnpm"
+```
+
+### Build artifacts between stages
+
+```yaml
+- uses: actions/upload-artifact@v4
+  with:
+    name: build-output
+    path: dist/
+    retention-days: 1
+```
+
+### Cache invalidation triggers
+
+| Change                      | Should bust cache                   |
+| --------------------------- | ----------------------------------- |
+| `package-lock.json` changed | Yes — deps cache                    |
+| Source code changed         | No — deps cache stays               |
+| `.env` / config changed     | Yes — if config is baked into build |
+| CI config changed           | Consider bust                       |
+
+---
+
+## Pipeline Optimization Checklist
+
+- [ ] Dependencies cached by lockfile hash
+- [ ] Lint and unit tests run in parallel
+- [ ] No sequential jobs that could be parallel
+- [ ] Test suite split if >5 minutes total
+- [ ] Build artifacts uploaded once, reused by deploy jobs
+- [ ] Docker layers ordered: deps first, code second (maximize cache hits)
+- [ ] Fail fast enabled (cancel in-progress on new push)
+- [ ] Skip CI for docs-only changes (`[skip ci]` or path filters)
+
+---
+
+## Fail-Fast Configuration
+
+```yaml
+# GitHub Actions — cancel in-progress on new push
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+```yaml
+# Path filters — skip CI for docs
+on:
+  push:
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
+```
+
+---
+
+## Secret Management Rules
+
+| Practice                             | Required    |
+| ------------------------------------ | ----------- |
+| Secrets in env vars, not hardcoded   | Yes         |
+| Rotate secrets on suspected exposure | Yes         |
+| Separate secrets per environment     | Yes         |
+| Least-privilege service accounts     | Yes         |
+| Audit secrets access in CI logs      | Recommended |
+
+**Scanning:** `truffleHog`, `gitleaks`, GitHub secret scanning (auto-enabled on public repos)
+
+---
+
+## Pipeline Health Metrics
+
+| Metric                       | Target  | Alert threshold |
+| ---------------------------- | ------- | --------------- |
+| Mean pipeline duration       | <10 min | >15 min         |
+| Success rate                 | >95%    | <90%            |
+| Flaky test rate              | <2%     | >5%             |
+| Cache hit rate               | >80%    | <60%            |
+| Time to restore (on failure) | <30 min | >60 min         |

package/content/plugins/delivery/skills/agileflow-delivery/references/pr-checklist-guide.md

@@ -0,0 +1,133 @@
+# PR Checklist Guide
+
+**Load this when:** preparing a pull request, reviewing a PR checklist,
+or deciding what checks are required before merge.
+
+## Core PR gates
+
+Every PR should clear these before merge:
+
+| Gate     | Check      | Command            |
+| -------- | ---------- | ------------------ |
+| Tests    | All pass   | `npm test`         |
+| Types    | No errors  | `tsc --noEmit`     |
+| Lint     | Clean      | `npm run lint`     |
+| Build    | Compiles   | `npm run build`    |
+| Coverage | ≥ baseline | `npm run coverage` |
+
+## PR description template
+
+```markdown
+## What
+
+[1-3 bullet points describing the change]
+
+## Why
+
+[The motivation — ticket, bug, user request]
+
+## How
+
+[Brief explanation of the approach chosen, especially if non-obvious]
+
+## Test plan
+
+- [ ] Unit tests cover new logic
+- [ ] Integration test for the happy path
+- [ ] Edge case X tested (explain if non-obvious)
+
+## Screenshots (UI changes only)
+
+[Before/after or just after if new feature]
+```
+
+## Size guidelines
+
+| PR size | Lines changed | Review time | Risk      |
+| ------- | ------------- | ----------- | --------- |
+| Tiny    | < 50          | 5 min       | Low       |
+| Small   | 50-200        | 15 min      | Low       |
+| Medium  | 200-500       | 30 min      | Medium    |
+| Large   | 500-1000      | 1 hour      | High      |
+| XL      | > 1000        | Split it    | Very high |
+
+**Rule:** If a PR exceeds 500 lines, look for a natural split. Reviewers lose focus above that threshold — bugs slip through.
+
+### How to split a large PR
+
+1. **Extract prerequisites** — dependency, config, or schema changes as a separate PR
+2. **Split by layer** — DB migration PR → API PR → UI PR
+3. **Feature flag** — ship dead code first, enable separately
+4. **One PR per file cluster** — group related files, ship independently
+
+## Commit message conventions
+
+```
+feat: add webhook delivery for Slack notifications
+fix: prevent duplicate delivery on retry
+refactor: extract delivery queue into separate module
+test: add integration tests for webhook retry logic
+docs: update delivery configuration reference
+chore: bump @slack/web-api to 7.3.0
+```
+
+**Never in commit messages:**
+
+- AI attribution footers
+- "WIP" or "temp" (clean up before merging)
+- Emoji prefixes unless your team convention requires them
+- "Fixed bug" with no specifics
+
+## Merge strategies
+
+| Strategy     | When to use          | Pros              | Cons                     |
+| ------------ | -------------------- | ----------------- | ------------------------ |
+| Squash merge | Feature branches     | Clean history     | Loses individual commits |
+| Rebase merge | Linear history teams | Clean graph       | Rewrites SHAs            |
+| Merge commit | Long-lived branches  | Preserves context | Noisy history            |
+
+**Default recommendation:** Squash merge for feature/fix branches. Merge commit for release branches.
+
+## Pre-merge checklist for large changes
+
+```
+⬜ Self-review: read every line of the diff
+⬜ Tests added for new behavior
+⬜ Tests updated for changed behavior
+⬜ No debug logs left in
+⬜ No hardcoded secrets or test credentials
+⬜ No commented-out code (delete it or leave it)
+⬜ Dependencies bumped in both package.json and lockfile
+⬜ Migrations reversible (if schema change)
+⬜ Feature flag added (if risk is high)
+⬜ Docs updated (if public API changed)
+```
+
+## Rollback plan
+
+For high-risk PRs, include in description:
+
+```markdown
+## Rollback plan
+
+- Revert commit: `git revert <sha>`
+- Migration rollback: `npm run db:rollback`
+- Feature flag: set `FF_NEW_CHECKOUT=false` in env
+```
+
+## Review SLAs (team norms to set)
+
+| PR size | Response time | Full review time |
+| ------- | ------------- | ---------------- |
+| Tiny    | 2 hours       | Same day         |
+| Small   | 4 hours       | Same day         |
+| Medium  | 1 day         | 2 days           |
+| Large   | 2 days        | 3 days           |
+
+## When to request additional reviewers
+
+- Touches auth or security → always add security-focused reviewer
+- Schema migration → add someone who knows the data model
+- Performance-critical path → add performance reviewer
+- Public API change → add API owner
+- Billing/payment → add a second reviewer minimum

package/content/plugins/delivery/skills/agileflow-delivery/references/release-checklist.md

@@ -0,0 +1,142 @@
+# Release Checklist
+
+**Load this when:** Preparing, executing, or verifying a software release — pre-release gates, deploy steps, and post-release validation.
+
+## Pre-Release Gates
+
+### Code quality
+
+- [ ] All CI checks passing on release branch
+- [ ] No critical or high CVEs in `npm audit` / security scan
+- [ ] Code review approved by at least one non-author
+- [ ] Feature flags set correctly for release scope
+
+### Testing
+
+- [ ] Unit + integration tests passing
+- [ ] Smoke tests passing on staging
+- [ ] Any manual QA sign-off completed (if required)
+- [ ] Regression tests run on affected paths
+- [ ] Performance benchmarks within budget (if perf-sensitive change)
+
+### Documentation
+
+- [ ] CHANGELOG updated with version and summary
+- [ ] API docs updated if contract changed
+- [ ] README version badge / install instructions current
+- [ ] Migration guide written if breaking change
+
+### Ops readiness
+
+- [ ] Feature flags configured for gradual rollout (if applicable)
+- [ ] Monitoring dashboards prepared for new metrics
+- [ ] Runbook updated if new failure modes introduced
+- [ ] On-call engineer notified of release window
+
+---
+
+## Release Execution Steps
+
+```
+1. Tag the release commit (semver, annotated tag)
+2. Push tag to trigger CI publish pipeline
+3. Monitor pipeline to completion
+4. Verify artifact published (npm, Docker Hub, GitHub Releases, etc.)
+5. Deploy to production (manual gate or auto on tag)
+6. Run post-deploy smoke tests
+7. Watch error rate / latency for 15 minutes
+8. Announce in team channel
+```
+
+---
+
+## Rollback Triggers
+
+Roll back immediately if within 30 minutes of deploy:
+
+| Signal                       | Threshold               |
+| ---------------------------- | ----------------------- |
+| Error rate increase          | >2x baseline            |
+| 5xx rate                     | >1% of requests         |
+| P95 latency                  | >2x pre-deploy baseline |
+| Critical user journey broken | Any                     |
+| Data corruption detected     | Any                     |
+| Payment / auth failure       | Any                     |
+
+Roll back after extended monitoring if:
+
+- Slow error rate increase over 1–4 hours
+- Memory leak detected (heap growth without plateau)
+- User reports of data inconsistency
+
+---
+
+## Rollback Decision Matrix
+
+| Time since deploy | Error severity | Rollback?                                           |
+| ----------------- | -------------- | --------------------------------------------------- |
+| <30 min           | Any            | Yes — immediate                                     |
+| 30 min–2h         | Critical/High  | Yes                                                 |
+| 30 min–2h         | Medium         | Hotfix preferred                                    |
+| >2h               | Any            | Hotfix strongly preferred; rollback if data at risk |
+
+**Rollback methods (in order of preference):**
+
+1. Feature flag disable (instant, no deploy)
+2. Revert deploy in CD platform (Vercel, Railway, etc.)
+3. `git revert` + fast-track deploy
+4. Database snapshot restore (last resort, data loss risk)
+
+---
+
+## Post-Release Validation (first 30 minutes)
+
+- [ ] Health endpoint returning 200
+- [ ] Error rate at or below pre-release baseline
+- [ ] P95 latency within 20% of baseline
+- [ ] Critical user journeys functional (smoke test)
+- [ ] Log stream clean (no unexpected errors)
+- [ ] New feature working as specified (spot check)
+
+---
+
+## Communication Templates
+
+### Release announcement (internal)
+
+```
+[RELEASE] v{version} — {title}
+
+What's new: {1–3 bullet summary}
+Deployed to: {environment(s)}
+Monitoring: {link to dashboard}
+Rollback plan: {feature flag / revert method}
+
+Needs attention? Ping @on-call
+```
+
+### Incident during release
+
+```
+[INCIDENT] Release v{version} — rollback initiated
+
+Impact: {what's affected}
+Root cause (preliminary): {hypothesis}
+Action taken: {rolled back to v{previous}}
+Status: {investigating / resolved}
+Updates in: #{incident-channel}
+```
+
+---
+
+## Versioning Rules (semver)
+
+| Change type                      | Bump            | Example        |
+| -------------------------------- | --------------- | -------------- |
+| Bug fix, patch-level             | PATCH           | 1.2.3 → 1.2.4  |
+| New feature, backward-compatible | MINOR           | 1.2.3 → 1.3.0  |
+| Breaking change                  | MAJOR           | 1.2.3 → 2.0.0  |
+| Pre-release                      | Pre-release tag | 2.0.0-alpha.1  |
+| Build metadata                   | Build tag       | 1.2.3+build.42 |
+
+**Breaking change examples:** Removed API endpoint, changed required field to required, renamed public method, dropped runtime support (Node version, browser).