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

package/content/plugins/engineering/plugin.yaml

@@ -0,0 +1,37 @@
+id: engineering
+name: Engineering
+description: Engineering skill pack.
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  skills:
+    - id: agileflow-engineering
+      dir: skills/agileflow-engineering
+  agents:
+    - id: api
+      path: agents/api.md
+    - id: codebase-query
+      path: agents/codebase-query.md
+    - id: compliance
+      path: agents/compliance.md
+    - id: database
+      path: agents/database.md
+    - id: integrations
+      path: agents/integrations.md
+    - id: mobile
+      path: agents/mobile.md
+    - id: monitoring
+      path: agents/monitoring.md
+    - id: performance
+      path: agents/performance.md
+    - id: refactor
+      path: agents/refactor.md
+    - id: security
+      path: agents/security.md
+    - id: ui
+      path: agents/ui.md
+  hooks: []
+  templates: []

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

@@ -0,0 +1,127 @@
+---
+name: agileflow-engineering
+version: 1.0.0
+category: agileflow/engineering
+description: |
+  Use when the user is implementing a specific technical domain: API
+  endpoints, database schema, UI components, mobile, security hardening,
+  performance optimization, integrations, compliance, or refactoring.
+  Routes to the right domain expert for the task.
+triggers:
+  keywords:
+    - build api
+    - database schema
+    - ui component
+    - security hardening
+    - integration
+    - mobile
+    - compliance
+    - monitoring
+    - implement
+    - build this feature
+  priority: 50
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/engineering.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [engineering]
+---
+
+# AgileFlow Engineering
+
+Domain expert routing for implementation work. Delegates to the right
+specialist based on what's being built.
+
+## When this skill activates
+
+- User wants to implement a specific technical feature
+- User asks for help with a domain-specific problem (DB, API, UI, etc.)
+- Babysit mentor needs to delegate implementation work
+
+## Domain experts
+
+| Command / Expert            | When to use                                               |
+| --------------------------- | --------------------------------------------------------- |
+| `/agileflow:api`            | REST endpoints, business logic, request/response handling |
+| `agileflow-database`        | Schema design, migrations, query optimization             |
+| `agileflow-ui`              | Components, styling, theming, accessibility               |
+| `agileflow-mobile`          | React Native, Flutter, cross-platform mobile              |
+| `agileflow-security`        | Auth, authorization, vulnerability analysis               |
+| `agileflow-performance`     | Profiling, optimization, benchmarking                     |
+| `agileflow-integrations`    | Third-party APIs, webhooks, payment processors            |
+| `agileflow-compliance`      | GDPR, HIPAA, SOC2, audit trails                           |
+| `agileflow-monitoring`      | Observability, logging, alerting, metrics                 |
+| `/agileflow:refactor`       | Technical debt, legacy code cleanup                       |
+| `/agileflow:codebase-query` | Search and understand the existing codebase               |
+
+## Routing logic
+
+```
+Single domain (DB only)     → delegate to agileflow-database
+Single domain (UI only)     → delegate to agileflow-ui
+Multi-domain (API + UI)     → delegate to agileflow-orchestrator
+Security concern            → always include agileflow-security
+Unknown codebase pattern    → /agileflow:codebase-query first
+```
+
+## Common flows
+
+**Add new API endpoint:**
+
+1. `agileflow-database` (schema if needed)
+2. `agileflow-api` (endpoint + business logic)
+3. `agileflow-testing` (tests)
+
+**Add UI feature:**
+
+1. `agileflow-ui` (component + styling)
+2. `agileflow-testing` (tests)
+3. Accessibility audit if interactive elements added
+
+## Integration
+
+### Before implementation
+
+- **agileflow-planning** — run an impact analysis before touching existing code; understand blast radius before writing anything
+- **agileflow-research** — activate when the story requires an unfamiliar library, API, or integration pattern; research resolves the unknowns before coding starts
+- **agileflow-council** — convene for architectural decisions that emerge mid-implementation: database choice, API design, service boundaries
+- **agileflow-adr** — create an ADR when a meaningful architecture or technology decision is made during implementation
+
+### During implementation
+
+- **agileflow-database** — delegate schema design, index planning, migration scripts, and query optimisation; engineering owns the feature, database owns the storage layer
+- **agileflow-debug** — hand off when hitting a persistent error after two different fix attempts; don't guess a third time
+- **agileflow-refactor** — use alongside implementation when the story explicitly involves cleaning up existing code before adding new functionality
+- **agileflow-migration** — use when the story involves upgrading a framework, library, or schema alongside the new feature work
+
+### After implementation
+
+- **agileflow-test-writer** — spawn to generate unit, integration, and E2E tests from the acceptance criteria after implementation completes
+- **agileflow-accessibility** — required after any UI or interactive element changes; invoke before marking the story done
+- **agileflow-performance** — invoke when the implementation touches query paths, renders, or data processing; confirm no regressions
+- **agileflow-audit** — run after implementation for P0/P1 sweep before merging into main
+- **agileflow-docs** — sync API docs, README, or configuration docs after any public-facing change
+- **agileflow-pr-reviewer** — invoke before creating the PR, especially for changes touching 5+ files
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                                 | When to load                                                                                                |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `references/domain-routing-guide.md` | Deciding which expert to delegate to — single vs multi-domain routing, parallel vs sequential execution     |
+| `references/code-review-guide.md`    | Reviewing code or preparing code for review — what to look for per layer, blocking vs non-blocking comments |
+| `references/refactoring-guide.md`    | Planning a refactor — when to refactor, extract vs inline decisions, naming conventions                     |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                    | When to follow                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `workflows/impact.md`   | User wants to understand the blast radius of a change before implementing       |
+| `workflows/diagnose.md` | User is stuck or wants to diagnose a bottleneck — systematic debugging approach |

package/content/plugins/engineering/skills/agileflow-engineering/references/code-review-guide.md

@@ -0,0 +1,126 @@
+# Code Review Guide
+
+**Load this when:** Conducting a code review, giving review feedback, or setting review standards.
+
+## Review Layers (check in this order)
+
+### 1. Correctness (blocking)
+
+- [ ] Does it do what the story/ticket describes?
+- [ ] Edge cases handled: null, empty, zero, max values, concurrent access
+- [ ] Error paths handled and errors surfaced appropriately
+- [ ] No silent failures (swallowed exceptions, unchecked return values)
+- [ ] State mutations are intentional and safe
+
+### 2. Security (blocking)
+
+- [ ] No secrets, tokens, or PII in code or logs
+- [ ] User input validated/sanitized before use
+- [ ] SQL: parameterized queries only
+- [ ] Auth checks present on new endpoints/routes
+- [ ] File paths constructed safely (no traversal risk)
+
+### 3. Tests (blocking)
+
+- [ ] New behavior has tests
+- [ ] Tests test behavior, not implementation
+- [ ] No tests commented out or skipped without explanation
+- [ ] Unhappy paths tested (errors, empty state, unauthorized)
+
+### 4. Design (non-blocking by default, blocking if severe)
+
+- [ ] Follows existing patterns in the codebase
+- [ ] No unnecessary abstraction (YAGNI)
+- [ ] No obvious performance issues (N+1 queries, unbounded loops)
+- [ ] Dependencies justified (not adding a package for one utility function)
+
+### 5. Readability (non-blocking, suggestions)
+
+- [ ] Variable/function names reveal intent
+- [ ] Complex logic has a comment explaining _why_, not _what_
+- [ ] Function length appropriate (suggest refactor if >50 lines)
+- [ ] Magic numbers/strings have named constants
+
+---
+
+## Feedback Tone Guide
+
+### Framing principles
+
+- Critique the code, never the person
+- Ask questions before asserting problems ("Could this be null here, or is it always set?")
+- Explain the _why_ behind every blocking comment
+- Lead with the positive when the overall PR is good
+
+### Blocking vs. Non-blocking
+
+| Label         | Meaning                | PR can merge?     |
+| ------------- | ---------------------- | ----------------- |
+| `blocking:`   | Must fix before merge  | No                |
+| `suggestion:` | Preferred but optional | Yes               |
+| `nit:`        | Tiny style preference  | Yes               |
+| `question:`   | Seeking understanding  | Yes, after answer |
+| `praise:`     | Call out good work     | Yes               |
+
+**Use inline labels.** Example:
+
+```
+blocking: This will throw if `user` is undefined. Add a null check or early return.
+
+suggestion: This could use `Array.from()` instead of `[...spread]` for clarity.
+
+nit: Missing semicolon on line 42.
+
+question: Is there a reason we're not using the existing `formatDate` utility here?
+```
+
+---
+
+## What NOT to Block On
+
+| Topic                                        | Handle it differently                                                  |
+| -------------------------------------------- | ---------------------------------------------------------------------- |
+| Formatting / whitespace                      | Enforce with a formatter (Prettier, ESLint). Never block PRs manually. |
+| Pure style preference                        | Use `nit:` or `suggestion:`, never `blocking:`                         |
+| "I would have done it differently"           | Only block if the approach has a concrete defect                       |
+| Missing tests for pre-existing untested code | Add a tech debt ticket; don't block the PR                             |
+
+---
+
+## Reviewer Efficiency Heuristics
+
+| PR size       | Suggested approach                                                          |
+| ------------- | --------------------------------------------------------------------------- |
+| <100 lines    | Full review all layers                                                      |
+| 100–400 lines | All layers; read all code                                                   |
+| 400–800 lines | All layers; focus on structure and interface design                         |
+| >800 lines    | Request split. If urgent: review architecture + security, defer readability |
+
+**Time budget:** ~1 hour per 400 lines. If taking longer, scope is too large.
+
+---
+
+## Common Code Smells to Flag
+
+| Smell                       | Blocking?  | Typical fix                                |
+| --------------------------- | ---------- | ------------------------------------------ |
+| `any` type in TypeScript    | Suggestion | Proper type or `unknown`                   |
+| `console.log` in prod code  | Blocking   | Remove or use logger                       |
+| Hardcoded URL/env value     | Blocking   | Move to config/env                         |
+| Commented-out code block    | Nit        | Delete it                                  |
+| Function with >3 parameters | Suggestion | Options object                             |
+| Deep nesting (>3 levels)    | Suggestion | Early return / extract function            |
+| Boolean parameter flags     | Suggestion | Named options object or separate functions |
+| `TODO` without issue link   | Nit        | Add issue reference                        |
+
+---
+
+## Approving a PR
+
+Approve when:
+
+- All blocking issues resolved
+- You understand what the code does and why
+- You'd be comfortable being woken up at 2am if it causes an incident
+
+Do NOT approve just to unblock — a ship-it with unresolved blocking issues is worse than a delay.

package/content/plugins/engineering/skills/agileflow-engineering/references/domain-routing-guide.md

@@ -0,0 +1,89 @@
+# Domain Routing Guide
+
+**Load this when:** deciding which expert to delegate to, or whether to use
+the orchestrator for multi-domain work.
+
+## Single-domain routing
+
+| Work involves...                                            | Route to                   | Notes                       |
+| ----------------------------------------------------------- | -------------------------- | --------------------------- |
+| SQL schema, migrations, indexes, ORM queries                | `agileflow-database`       | Always for schema changes   |
+| REST endpoints, GraphQL, business logic, request handling   | `agileflow-api`            | Backend routes and services |
+| React/Vue/Angular components, CSS, theming, accessibility   | `agileflow-ui`             | Frontend presentation layer |
+| React Native, Flutter, iOS, Android, cross-platform         | `agileflow-mobile`         | Mobile-specific concerns    |
+| Auth flows, authorization, vulnerability analysis, pen test | `agileflow-security`       | Any security-sensitive code |
+| Profiling, caching, query optimization, bundle size         | `agileflow-performance`    | Performance bottlenecks     |
+| Stripe, Twilio, SendGrid, OAuth, external APIs              | `agileflow-integrations`   | Third-party service wiring  |
+| GDPR, HIPAA, SOC2, audit logging, compliance docs           | `agileflow-compliance`     | Regulatory requirements     |
+| Prometheus, Grafana, Datadog, logging, alerting             | `agileflow-monitoring`     | Observability setup         |
+| Legacy code cleanup, extracting functions, naming           | `agileflow-refactor`       | Technical debt work         |
+| Codebase exploration, finding patterns, understanding code  | `agileflow-codebase-query` | Discovery and research      |
+
+## Multi-domain routing → orchestrator
+
+Use `agileflow-orchestrator` when work spans 2+ domains:
+
+| Example work                  | Domains involved                 |
+| ----------------------------- | -------------------------------- |
+| New user profile feature      | API + UI (+ DB if schema change) |
+| Payment integration           | API + Security + Integrations    |
+| Real-time notifications       | API + UI + Monitoring            |
+| New data model with endpoints | DB + API                         |
+| Auth system                   | API + Security + UI              |
+| Performance investigation     | DB + Performance + Monitoring    |
+
+## Parallel vs sequential expert execution
+
+```
+Independent domains → run in PARALLEL (faster)
+  Example: UI component + API endpoint (neither needs the other's output)
+
+Dependent domains → run SEQUENTIALLY
+  Example: DB schema → API endpoint → UI (each builds on previous)
+  Common order: Database → API → UI → Tests
+```
+
+## When to involve security
+
+**Always involve `agileflow-security` when:**
+
+- Authentication or session management changes
+- New API endpoints that accept user input
+- File upload functionality
+- Payment or financial data handling
+- User permission or role changes
+- New third-party integrations that receive webhooks
+- Any data encryption or key management
+
+Security review doesn't block other experts — run it in parallel with API/UI work,
+then review findings before committing.
+
+## Testing
+
+`agileflow-testing` is for test strategy and comprehensive test suites.
+For quick test additions alongside implementation, the domain expert handles it directly.
+
+Use `agileflow-testing` when:
+
+- Coverage is systematically low and needs a strategy
+- Complex testing setup (mocking, fixtures, test data)
+- End-to-end test suite design
+- Test quality audit results show structural problems
+
+## When to use multi-expert vs orchestrator
+
+| Need                                             | Use                       |
+| ------------------------------------------------ | ------------------------- |
+| Implement a feature across 2+ domains            | `agileflow-orchestrator`  |
+| Get multiple opinions/analysis on the same thing | `/agileflow:multi-expert` |
+| Review code for correctness                      | `agileflow-code-reviewer` |
+| Architecture decision                            | `/agileflow:council`      |
+
+## Escalation triggers
+
+Escalate from single expert to orchestrator mid-task if:
+
+- Expert discovers the work spans more domains than expected
+- Schema change is needed (always add `agileflow-database`)
+- Security issue found (always add `agileflow-security`)
+- Performance problem discovered (add `agileflow-performance`)

package/content/plugins/engineering/skills/agileflow-engineering/references/refactoring-guide.md

@@ -0,0 +1,136 @@
+# Refactoring Guide
+
+**Load this when:** Deciding whether to refactor, choosing a refactoring technique, or reviewing a refactoring PR.
+
+## When to Refactor
+
+### Strong signals (do it)
+
+- [ ] Same logic copy-pasted in 3+ places
+- [ ] Function >50 lines doing multiple things
+- [ ] Adding a feature requires understanding >200 lines of tangled code first
+- [ ] Tests are brittle because they depend on implementation details
+- [ ] Name of function/variable no longer describes what it does
+
+### Weak signals (consider it)
+
+- Code works but feels awkward to navigate
+- New team members consistently get confused in this area
+- The same area keeps appearing in bug reports
+
+### Do NOT refactor when
+
+- You're in a code freeze or release window
+- You don't have test coverage to verify behavior is preserved
+- The refactoring would touch >500 lines without a clear benefit
+- You're on a deadline and the code works
+
+**Rule of three:** Fix inline once, extract on the second instance, refactor on the third.
+
+---
+
+## Extract vs. Inline Decision
+
+### Extract (create a new function/module) when
+
+- Logic is reused in 2+ places
+- A block of code has a single, nameable purpose
+- The function is testable in isolation
+- The enclosing function is doing too many things
+
+### Inline (collapse a function/variable back) when
+
+- The function is called from exactly one place
+- The abstraction adds no clarity — you have to read the definition to understand the call
+- A variable just aliases another variable (`const x = y; doThing(x)`)
+
+---
+
+## Core Refactoring Techniques
+
+| Technique                                      | When to use                               | Risk   |
+| ---------------------------------------------- | ----------------------------------------- | ------ |
+| Extract function                               | Block of code with a clear single purpose | Low    |
+| Rename                                         | Name no longer reflects purpose           | Low    |
+| Extract variable                               | Complex expression used multiple times    | Low    |
+| Inline function                                | One-use wrapper adds no clarity           | Low    |
+| Move function                                  | Function belongs in a different module    | Medium |
+| Replace conditional with polymorphism          | Long if/switch on type                    | Medium |
+| Extract class/module                           | File doing unrelated things               | Medium |
+| Replace magic number with named constant       | Unexplained literal values                | Low    |
+| Introduce parameter object                     | Function with >3 related params           | Low    |
+| Replace nested conditionals with guard clauses | Deep nesting                              | Low    |
+
+---
+
+## Guard Clause Pattern (flatten nesting)
+
+**Before:**
+
+```js
+function process(user) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasPermission("admin")) {
+        // actual logic
+      }
+    }
+  }
+}
+```
+
+**After:**
+
+```js
+function process(user) {
+  if (!user) return;
+  if (!user.isActive) return;
+  if (!user.hasPermission("admin")) return;
+  // actual logic — unindented, readable
+}
+```
+
+---
+
+## Naming Conventions
+
+| Pattern                      | Wrong                       | Right                                    |
+| ---------------------------- | --------------------------- | ---------------------------------------- |
+| Boolean variables            | `flag`, `status`, `data`    | `isActive`, `hasPermission`, `canEdit`   |
+| Functions that return values | `userData()`, `processIt()` | `getUser()`, `formatDate()`              |
+| Event handlers               | `click()`, `handler()`      | `handleSubmit()`, `onUserCreated()`      |
+| Async functions              | Same as sync                | `fetchUser()`, `loadConfig()`            |
+| Generic array names          | `list`, `arr`, `items`      | `users`, `activeOrders`, `errorMessages` |
+
+---
+
+## Refactoring Safely
+
+### Required before starting
+
+1. Ensure test coverage for the area being refactored
+2. Commit current state ("before" snapshot)
+3. Define what "done" looks like — what are you making better?
+
+### During
+
+- One refactoring technique at a time
+- Commit after each atomic change
+- Run tests after each commit (never let tests break between commits)
+
+### After
+
+- All existing tests still pass
+- New tests cover any previously untested behavior
+- Code review confirms intent is clear
+
+---
+
+## Refactoring PR Checklist
+
+- [ ] No behavior changes — only structure
+- [ ] Tests pass without modification (or test names updated to match new names)
+- [ ] PR description explains _why_ this refactoring, not just what changed
+- [ ] No new features bundled in (keep refactoring PRs pure)
+- [ ] Performance not degraded (run benchmarks if relevant)
+- [ ] PR is reviewable (not 2,000 lines of renames — consider splitting)

package/content/plugins/engineering/skills/agileflow-engineering/workflows/diagnose.md

@@ -0,0 +1,63 @@
+# Diagnose Workflow — System Health Check
+
+**Triggers:** "something feels off with AgileFlow", "run diagnostics", "check system health", "diagnose the setup", "AgileFlow not working right", "validate the installation"
+
+**Goal:** Run comprehensive health checks on the AgileFlow installation — validate JSON files, check the hooks system, verify auto-archival config, and report file size warnings — with clear PASS/FAIL/WARN indicators.
+
+## Inputs needed
+
+None — runs full diagnostics automatically.
+
+## Steps
+
+1. Run JSON file validation on all critical files using `jq empty`:
+   - `docs/09-agents/status.json`
+   - `docs/00-meta/agileflow-metadata.json`
+   - `.claude/settings.json`
+     Report: file size, valid/invalid status. For invalid files, show the parse error.
+
+2. Check file size thresholds:
+   - `status.json` over 50KB → warn: recommend archiving completed stories
+   - `status.json` over 100KB → critical: use `jq '.stories | length'` to count stories
+
+3. Validate the auto-archival system:
+   - Check if the archive script exists and is executable (`-x` check)
+   - Verify the hook is configured in `.claude/settings.json` (check for the SessionStart hook referencing the archive script)
+   - Read the archival threshold from metadata
+
+4. Validate the hooks system:
+   - Parse `.claude/settings.json` structure
+   - Count SessionStart, UserPromptSubmit, and Stop hooks
+   - Flag missing hooks or misconfigurations
+
+5. Check file structure integrity — verify these directories exist:
+   - `docs/09-agents/`
+   - `docs/00-meta/`
+   - `.agileflow/`
+   - `.claude/`
+
+6. Generate the health report with status indicators:
+   - Pass: check passed
+   - Fail: issue found, action needed
+   - Warn: potential issue, monitor
+   - Info: informational only
+
+7. If any failures are found, list them with specific fix instructions. If all checks pass, confirm the system is healthy.
+
+8. Ask the user: [A] Fix the listed issues now (if any failures), [B] Archive completed stories (if size warning), [C] No action needed.
+
+## Output
+
+Health report with check results for JSON validation, auto-archival, hooks system, and file sizes. Specific fix instructions for any failures. Exit summary: N passed, M warnings, K failures.
+
+## 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/engineering/skills/agileflow-engineering/workflows/impact.md

@@ -0,0 +1,60 @@
+# Impact Workflow — Code Change Impact Analysis
+
+**Triggers:** "what will this change break", "impact analysis", "what tests should I run", "show me what depends on this file", "check for breaking changes", "what's affected by my changes"
+
+**Goal:** Build a dependency graph for recently changed files, identify direct and indirect callers, detect breaking changes, and produce a risk-scored impact report with actionable test recommendations.
+
+## Inputs needed
+
+| Input         | Required | How to get it                                 |
+| ------------- | -------- | --------------------------------------------- |
+| changed files | No       | Auto-detected from `git diff` if not provided |
+| base branch   | No       | Default: `main`                               |
+| run tests     | No       | Default: yes if tests are found               |
+
+## Steps
+
+1. Detect changed files. If files are not specified, run `git diff <base> --name-only` to get the list. If no changes are staged, ask: "Which files should I analyze? (paste paths or describe the change)"
+
+2. For each changed file, build the dependency graph:
+   - **Direct imports**: which files import this file
+   - **Indirect imports**: files that import the direct importers (2 levels deep)
+     Show the graph as a table: changed file → callers → callers-of-callers.
+
+3. Detect breaking changes in each modified file:
+   - Function signature changes (parameters added/removed/reordered)
+   - Exported type modifications
+   - Return type changes
+   - Removed exports
+     Mark each as: breaking (callers will fail) or non-breaking (additive change).
+
+4. Find related tests:
+   - Unit tests that import or reference the changed files
+   - Integration tests in the same module area
+   - E2E tests that exercise the affected user flows
+     Use both pattern matching (file naming conventions) and coverage mapping if available.
+
+5. Generate the impact report with risk scores:
+   - **Critical**: breaking changes with known callers
+   - **Recommended**: non-breaking changes but callers should be tested
+   - **Optional**: test files in the same area, low change risk
+
+6. Show the impact report. Ask: [A] Run the affected tests now (recommended), [B] Show me the full caller list for a specific file, [C] Just the report — I'll run tests myself.
+
+7. If running tests, execute the critical and recommended test files. Report results: pass/fail with counts and any new failures.
+
+## Output
+
+Impact report with changed files, dependency graph (2 levels), breaking change detection, related tests by risk level. Optional: test run results.
+
+## 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
+```