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

package/content/plugins/council/skills/agileflow-council/references/decision-log-template.md

@@ -0,0 +1,109 @@
+# Decision Log Template
+
+**Load this when:** Recording a council decision, drafting an ADR, or documenting a significant architectural or product choice.
+
+## Decision Record Format
+
+```markdown
+# DR-[NNN]: [Short descriptive title]
+
+**Date:** YYYY-MM-DD
+**Status:** Proposed | Accepted | Deprecated | Superseded by DR-NNN
+**Deciders:** [Names or roles who have authority to accept this]
+**Council perspectives consulted:** [e.g., Technical, Revenue, Advocate, Contrarian]
+
+---
+
+## Context
+
+[2–4 sentences. What situation prompted this decision? What constraints exist?
+Include relevant metrics, deadlines, or dependencies.]
+
+## Decision
+
+[1–3 sentences. The actual choice made. Start with "We will..." or "We decided to..."]
+
+## Options Considered
+
+| Option            | Pros | Cons | Ruled out because |
+| ----------------- | ---- | ---- | ----------------- |
+| Option A (chosen) | ...  | ...  | —                 |
+| Option B          | ...  | ...  | ...               |
+| Option C          | ...  | ...  | ...               |
+
+## Consequences
+
+**Positive:**
+
+- [Benefit 1]
+- [Benefit 2]
+
+**Negative / trade-offs:**
+
+- [Trade-off 1]
+- [Accepted risk: ...]
+
+**Neutral / follow-on actions:**
+
+- [ ] [Action item with owner]
+- [ ] [Action item with owner]
+
+## Dissenting Views
+
+[Any perspectives not reflected in the final decision. Optional but valuable for future context.]
+
+## Review Trigger
+
+[When should this decision be revisited? e.g., "If user adoption of X falls below Y%", "At 6-month mark", "When we exceed N customers"]
+```
+
+---
+
+## Decision Severity Classification
+
+| Level            | Criteria                                              | Example                         | Review cycle            |
+| ---------------- | ----------------------------------------------------- | ------------------------------- | ----------------------- |
+| L1 — Critical    | Affects architecture, data model, or security posture | "Switch from REST to GraphQL"   | Quarterly or on trigger |
+| L2 — Significant | Affects multiple teams or user-facing behavior        | "Add feature flag system"       | 6-month or on trigger   |
+| L3 — Routine     | Contained within one area, reversible                 | "Choose between library A vs B" | Annual or on migration  |
+
+---
+
+## Status Transitions
+
+```
+Proposed → Accepted     (after council + stakeholder sign-off)
+Accepted → Deprecated   (superseded but context still valuable)
+Accepted → Superseded   (replaced by newer DR — link to it)
+Proposed → Rejected     (not pursued — record why for future reference)
+```
+
+---
+
+## Filing Convention
+
+```
+docs/04-architecture/decisions/
+├── DR-001-use-postgresql.md
+├── DR-002-api-versioning-strategy.md
+└── DR-003-frontend-framework.md
+```
+
+**Numbering:** Sequential, never reuse. Rejected decisions still get a number.
+
+---
+
+## Quick-Capture Format (for time-constrained decisions)
+
+When speed matters, minimum viable record:
+
+```markdown
+# DR-[NNN]: [Title]
+
+Date: YYYY-MM-DD | Status: Accepted | Deciders: [names]
+
+**Decision:** [One sentence]
+**Because:** [One sentence rationale]
+**Trade-off accepted:** [One sentence]
+**Review if:** [Trigger condition]
+```

package/content/plugins/council/skills/agileflow-council/references/perspective-guide.md

@@ -0,0 +1,104 @@
+# Council Perspective Guide
+
+**Load this when:** convening the council, interpreting perspective outputs,
+or explaining what each agent argues for.
+
+## The eight perspectives
+
+### Technical Architect
+
+_Evaluates through engineering feasibility, system design, and technical debt_
+
+Optimizes for: correctness, maintainability, scalability
+Asks: "Can we actually build this? What breaks? What debt does it create?"
+Typical concerns: API contracts, database schema implications, migration complexity,
+test coverage, backwards compatibility, performance at scale
+Red flags they raise: premature optimization, over-engineering, under-engineering,
+missing error handling, tight coupling
+
+### Revenue Strategist
+
+_Gravitational pull toward shipping, selling, and collecting money within 90 days_
+
+Optimizes for: near-term revenue impact, time-to-value
+Asks: "Does this move a number that matters in the next quarter?"
+Typical concerns: feature-market fit, pricing implications, sales cycle impact,
+customer acquisition cost, payback period
+Will push back on: anything that delays shipping, internal tooling over customer features,
+perfection over progress
+
+### Optimist Strategist
+
+_Identifies opportunities, best-case scenarios, and success pathways_
+
+Optimizes for: upside potential, momentum, positive framing
+Asks: "What does success look like? What could go unexpectedly right?"
+Typical concerns: market timing, network effects, first-mover advantage,
+user delight potential
+Useful for: generating energy behind a decision, identifying hidden upside
+Watch out for: can underweight risks — balance with Advocate
+
+### Devil's Advocate
+
+_Critical examination of risks, blind spots, and stress-testing assumptions_
+
+Optimizes for: finding what's wrong before it's too late
+Asks: "What are we assuming that might be false? What's the worst case?"
+Typical concerns: dependency risks, user adoption barriers, competitive threats,
+regulatory risks, technical unknowns, team capability gaps
+Useful for: pre-mortem analysis, stress-testing plans
+Watch out for: can paralyze if taken too far — balance with Optimist
+
+### Contrarian Thinker
+
+_Challenges consensus, questions assumptions, finds value in the unpopular position_
+
+Optimizes for: avoiding groupthink, surfacing overlooked alternatives
+Asks: "What if everyone is wrong? What's the opposite of what we're assuming?"
+Typical concerns: industry assumptions worth challenging, conventional wisdom that doesn't apply here
+Different from Advocate: Advocate looks for risks in the plan; Contrarian questions whether the plan is even the right question
+Useful for: major pivots, when the obvious answer feels too obvious
+
+### Compounder Strategist
+
+_Identifies compounding advantages, moats, and multi-quarter value accumulation_
+
+Optimizes for: decisions that get better over time, not just good now
+Asks: "Does this compound? Does this build a moat? Will we regret this in 2 years?"
+Typical concerns: data flywheels, network effects, switching costs, brand equity,
+platform lock-in potential, technical debt accumulation
+Useful for: architecture decisions, product strategy, build vs buy
+
+### Moonshot Thinker
+
+_Advocates for 10x moves, category-defining bets, and trajectory-changing plays_
+
+Optimizes for: discontinuous impact, not incremental improvement
+Asks: "What would 10x better look like? Are we solving the right problem?"
+Typical concerns: whether we're optimizing a local maximum, paradigm shifts, AI/automation leverage
+Useful for: product vision, long-term roadmap, when incremental feels insufficient
+Watch out for: not every decision needs a moonshot take — use selectively
+
+### Neutral Analyst
+
+_Objective analysis, trade-off evaluation, evidence-based synthesis_
+
+Optimizes for: accuracy, completeness, balanced view
+Asks: "What does the evidence say? What are the actual trade-offs?"
+Role: synthesizes all other perspectives into a ranked recommendation
+Produces: final recommendation with reasoning, risks acknowledged, dissenting views noted
+
+## How to read council output
+
+1. **Look for convergence** — if 5+ perspectives agree, the answer is likely clear
+2. **Look for the split** — if Technical and Revenue disagree strongly, that's the real decision
+3. **Weight by context** — early-stage startup: weight Revenue and Moonshot; mature product: weight Technical and Compounder
+4. **Trust the Analyst synthesis** — but read the Advocate dissent before accepting
+
+## When not to convene the council
+
+- Simple implementation decisions (which library, file structure) → just decide
+- Clear-cut technical choices with an obvious right answer → Technical alone
+- Urgent fixes where deliberation costs more than the risk → just fix it
+
+The council is for decisions where reasonable people disagree and the stakes are high enough to justify deliberation time.

package/content/plugins/council/skills/agileflow-council/references/when-to-convene-guide.md

@@ -0,0 +1,112 @@
+# When to Convene the Council
+
+**Load this when:** Deciding whether a question warrants full council deliberation or can be resolved immediately.
+
+## Decision Tree
+
+```
+Is the decision reversible within 1 sprint?
+  YES → Decide now. Document briefly. No council needed.
+  NO  ↓
+
+Does it affect more than one team or system boundary?
+  NO  → Team decides. Record in DR log. No council needed.
+  YES ↓
+
+Is it time-sensitive (must decide in <2 hours)?
+  YES → Emergency council: 2–3 perspectives max, async if needed.
+  NO  ↓
+
+Convene full council.
+```
+
+---
+
+## Trigger Checklist — Convene When Any Apply
+
+### Architecture / Technical
+
+- [ ] Introducing a new service, database, or data store
+- [ ] Changing the API contract (breaking or additive)
+- [ ] Adding a new infrastructure dependency (cloud service, SaaS)
+- [ ] Proposing a migration >500 lines of affected code
+- [ ] Security-impacting change (auth, authz, secrets, PII handling)
+- [ ] Performance trade-off that degrades another system
+
+### Product / Business
+
+- [ ] Feature that changes the core user journey
+- [ ] Pricing, packaging, or trial model change
+- [ ] Deprecating a user-facing feature
+- [ ] Launch decision (go/no-go) with revenue implications
+- [ ] Policy change affecting compliance (GDPR, HIPAA, etc.)
+
+### Process / Team
+
+- [ ] Changing team structure or ownership boundaries
+- [ ] Adopting a new tool that affects all engineers
+- [ ] Incident post-mortem with systemic findings
+- [ ] Budget allocation above agreed threshold
+
+---
+
+## Skip the Council When
+
+| Situation                             | What to do instead                           |
+| ------------------------------------- | -------------------------------------------- |
+| Clear best practice exists            | Implement it, note the reference             |
+| Reversible in <1 sprint               | Decide, ship, observe                        |
+| Already decided by a prior DR         | Follow the prior DR                          |
+| Purely aesthetic / style choice       | Follow style guide                           |
+| One person has clear domain ownership | Let them decide                              |
+| Urgency overrides deliberation        | Timebox to 30 min, decide, post-mortem later |
+
+---
+
+## Council Format by Urgency
+
+### Async (default — use for most decisions)
+
+- Post the question + context doc in the team channel
+- Tag each perspective holder
+- 24-hour comment window
+- Decision maker synthesizes and posts DR
+
+### Synchronous (use when debate is needed)
+
+- Max 4 perspectives in the room
+- 25-minute timebox: 10 context, 10 debate, 5 decide
+- One person plays Devil's Advocate if no natural Contrarian
+
+### Emergency (production incident or hard deadline)
+
+- 2–3 people max
+- Async notes captured in real-time (shared doc)
+- Full DR written within 24 hours post-decision
+
+---
+
+## Perspective Roles — When to Include Each
+
+| Role       | Include when                                       |
+| ---------- | -------------------------------------------------- |
+| Technical  | Any architecture, infra, or code-level decision    |
+| Revenue    | Feature prioritization, pricing, conversion impact |
+| Advocate   | UX/DX changes, customer-facing behavior            |
+| Contrarian | High-confidence proposals (prevent groupthink)     |
+| Optimist   | Morale-impacting changes, long-horizon bets        |
+| Moonshot   | Exploring whether we're thinking too small         |
+
+**Minimum viable council:** Technical + Advocate + Contrarian (3 perspectives).
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-pattern                                    | Why it's harmful                                   |
+| ----------------------------------------------- | -------------------------------------------------- |
+| Convening council for every decision            | Slows teams; dilutes significance of real councils |
+| Skipping council for major architecture changes | Creates unreviewed technical debt                  |
+| Stacking council with only aligned perspectives | Produces echo-chamber decisions                    |
+| Council without a decision maker                | Produces discussion, not decisions                 |
+| Reopening accepted DRs without new information  | Wastes time; undermines trust in the process       |

package/content/plugins/council/skills/agileflow-council/workflows/convene.md

@@ -0,0 +1,73 @@
+# Convene Workflow — AI Council for Strategic Decisions
+
+**Triggers:** "convene the council", "agents gather", "council assemble", "get three perspectives on", "I need balanced advice on", "strategic decision about", "should we adopt X", "GraphQL vs REST", "build vs buy"
+
+**Goal:** Deploy three AI council perspectives (Optimist, Devil's Advocate, Neutral Analyst) on a strategic question, then synthesize into a recommendation with confidence level.
+
+## Inputs needed
+
+| Input    | Required | How to get it                                                                              |
+| -------- | -------- | ------------------------------------------------------------------------------------------ |
+| question | Yes      | Ask if not provided: "What decision or question should the council deliberate on?"         |
+| mode     | No       | Default: parallel. Options: parallel (single round), debate (agents respond to each other) |
+| rounds   | No       | Only for debate mode. Default: 2                                                           |
+
+## When to use this workflow
+
+Best for strategic, non-technical decisions where balanced perspectives matter:
+
+- Architecture decisions ("Should we adopt microservices?")
+- Technology choices ("GraphQL vs REST for our API?")
+- Process decisions ("Should we implement feature flags?")
+- Business tradeoffs ("Build vs buy for this feature?")
+
+Not for: code implementation tasks, simple questions with clear answers, or research tasks.
+
+## Steps
+
+1. Get the question from the user if not already stated. If the question is vague, help them sharpen it: "Is this primarily a technical decision, a resource decision, or a strategic direction decision?"
+
+2. Ask the user: "Which mode? [A] Parallel (all three perspectives at once, then synthesis — recommended for most decisions), [B] Debate (agents respond to each other across multiple rounds — better for nuanced tradeoffs)."
+
+3. Create a session folder at `.agileflow/council/sessions/<timestamp>/`.
+
+4. **Parallel mode:** Deploy all three council members simultaneously:
+   - **Optimist Strategist** — best-case scenarios, opportunities, success pathways, why this could work
+   - **Devil's Advocate** — risks, blind spots, assumptions to stress-test, why this could fail
+   - **Neutral Analyst** — trade-off analysis, evidence synthesis, decision criteria, what data would change the answer
+
+   Each member receives: the full question, project context (read `package.json` or `CLAUDE.md`), and their specific role prompt.
+
+5. **Debate mode:** Run the first round as parallel above. Then share each agent's perspective with the others and run a second round where they respond to what the others said. Repeat for the configured number of rounds.
+
+6. Collect all perspectives. Write them to `shared_reasoning.md` in the session folder.
+
+7. Synthesize:
+   - **Common Ground** — what all three perspectives agree on
+   - **Key Tensions** — where they fundamentally differ and why
+   - **Recommendation** — a specific decision with confidence level (High/Medium/Low) and the reasoning
+
+8. Present the full deliberation with: individual perspective summaries, synthesis section, and recommended next steps.
+
+9. Ask the user: [A] Proceed with the recommendation, [B] Dig into the Devil's Advocate concerns, [C] Request a second debate round, [D] Save this session.
+
+## Output
+
+Deliberation written to `.agileflow/council/sessions/<timestamp>/shared_reasoning.md`. Synthesis with recommendation and confidence level. Next steps.
+
+## 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. Fix the P0 findings now
+2. Review full findings first
+3. Export report only
+```
+
+**If agent spawning (Task tool / multi-agent) is unavailable:**
+Perform each analysis inline and sequentially instead of spawning parallel agents.
+Work through the key checks for each domain yourself using the reference files in `references/`.
+Consolidate findings into the same structured output format — the user gets the same result, just slower.

package/content/plugins/council/skills/agileflow-council/workflows/multi-expert.md

@@ -0,0 +1,75 @@
+# Multi-Expert Workflow — Parallel Domain Expert Analysis
+
+**Triggers:** "get multiple experts to look at this", "multi-expert analysis", "deploy domain experts on", "get high confidence on", "ask security AND performance about this", "is our auth implementation secure"
+
+**Goal:** Select 3–5 domain experts based on the question, deploy them simultaneously, and synthesize their independent findings into a confidence-scored report.
+
+## Inputs needed
+
+| Input    | Required | How to get it       |
+| -------- | -------- | ------------------- |
+| question | Yes      | Ask if not provided |
+
+## Available experts
+
+Security, API, Testing, Database, Performance, CI/CD, DevOps, Accessibility, Architecture, UI, Mobile, Monitoring, Documentation, Integrations
+
+## Steps
+
+1. Get the question from the user if not provided.
+
+2. Detect which domains are relevant from the question. Use these keyword signals:
+   - **Security**: auth, JWT, OAuth, vulnerability, XSS, CSRF, secure, encrypt, password, token
+   - **Performance**: slow, cache, optimize, latency, bundle, memory, render, query
+   - **API**: endpoint, REST, GraphQL, versioning, rate limit, payload
+   - **Testing**: coverage, unit test, integration test, mock, assertion, flaky
+   - **Database**: schema, migration, query, index, join, N+1, postgres, mongo
+   - **Architecture**: coupling, dependency, patterns, layering, circular, complexity
+   - **Accessibility**: ARIA, keyboard, screen reader, WCAG, contrast, focus
+   - **UI**: component, styling, responsive, layout, UX, design
+
+3. Select 3–5 experts (maximum 5 to avoid synthesis overhead). Tell the user: "I'll deploy these experts: [list]. Approve or adjust?" Options: [A] Looks good, deploy, [B] Add [expert], [C] Remove [expert].
+
+4. Deploy all selected experts simultaneously. Each expert receives: the question, project context, and their specific domain lens. They are asked to: observe what they see in their domain, flag concerns or issues, provide specific recommendations with file paths if applicable, and state their confidence level (High/Medium/Low) with reasoning.
+
+5. Collect all expert outputs. Synthesize with confidence scoring:
+   - **HIGH confidence**: 3+ experts agree on the same finding or recommendation
+   - **MEDIUM confidence**: 2 experts agree
+   - **UNIQUE insight**: 1 expert identified something the others didn't — flag for verification
+   - **Disagreement**: experts reached different conclusions on the same point — flag for human review
+
+6. Present the synthesis report:
+   - **Key Findings** (HIGH confidence) — findings confirmed by multiple experts
+   - **Unique Insights** — single-expert findings worth reviewing
+   - **Disagreements** — where experts diverged and why
+   - **Recommended Actions** — specific, prioritized steps with confidence ratings
+
+7. Ask the user: [A] Act on the top recommendation, [B] Drill into a specific expert's findings, [C] Run a second round with additional context, [D] Save this analysis.
+
+## Confidence scoring explained
+
+- HIGH (3+ experts agree): Act on this confidently
+- MEDIUM (2 experts agree): Likely valid, review the reasoning
+- UNIQUE (1 expert, with evidence): Interesting — verify before acting
+- DISAGREEMENT: Don't act until resolved — present both positions to the user
+
+## Output
+
+Synthesis report with confidence-scored findings. Prioritized action list. The analysis is available for appending to research notes or linking to a story.
+
+## 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. Fix the P0 findings now
+2. Review full findings first
+3. Export report only
+```
+
+**If agent spawning (Task tool / multi-agent) is unavailable:**
+Perform each analysis inline and sequentially instead of spawning parallel agents.
+Work through the key checks for each domain yourself using the reference files in `references/`.
+Consolidate findings into the same structured output format — the user gets the same result, just slower.

package/content/plugins/database/plugin.yaml

@@ -0,0 +1,14 @@
+id: database
+name: Database
+description: Schema design, query optimization, indexing strategy, and safe migrations.
+version: 1.0.0
+enabledByDefault: false
+cannotDisable: false
+depends: []
+provides:
+  skills:
+    - id: agileflow-database
+      dir: skills/agileflow-database
+  agents: []
+  hooks: []
+  templates: []