@mark-gozner/aigile-method 0.4.5

package/core/tasks/document-project.md

@@ -0,0 +1,69 @@
+<!-- Inspired by BMAD™ Document Project; scoped to AIgile core-config -->
+
+# Architect Task: Document Project (Brownfield Reality)
+
+## Purpose
+
+Create a concise, practical architecture document that reflects the system as it actually exists. Focus on the parts relevant to upcoming work; reference files instead of duplicating content. Optimize for AI and human contributors to quickly orient and make safe changes.
+
+## Inputs
+
+```yaml
+config:
+  architectureFile: docs/architecture.md
+  architectureSharded: true
+  architectureShardedLocation: docs/architecture
+  devStoryLocation: docs/stories
+```
+
+## Preconditions
+
+- Check if a PRD or specific enhancement goal exists; if yes, scope docs to impacted areas
+- Confirm repository build/readme exists; note missing pieces as “gaps”
+
+## Process (Sequential)
+
+1. Scope the Work
+	- If PRD/enhancement exists, list modules likely impacted and limit depth to those
+	- If no scope, cover the essentials: tech stack, structure, key modules, constraints
+2. Discover the Reality
+	- Identify entry points, configuration, and environment setup
+	- Map repository structure and naming conventions actually used
+	- Note workarounds/legacy areas that cannot change
+3. Capture Core Architecture
+	- Tech Stack summary (runtime, frameworks, DB, queues)
+	- Project structure overview with notable deviations from standards
+	- Key modules and responsibilities (with file paths)
+	- Integration points (internal and external) with locations
+4. Constraints and Debt
+	- Document technical debt, “gotchas,” and non-negotiable constraints
+	- Link to ADRs if present; otherwise, add inline rationale bullets
+5. Testing & Operations
+	- Testing strategy status (unit/integration/e2e; coverage reality)
+	- Build and deployment process as it actually works today
+6. Deliverable
+	- Create or update `docs/architecture.md` or sharded files under `docs/architecture/`
+	- Keep sections short; link to source files and configs
+
+## Suggested Sections (Sharded)
+
+- tech-stack.md
+- unified-project-structure.md (aka source-tree.md)
+- coding-standards.md
+- backend-architecture.md / frontend-architecture.md (if applicable)
+- data-models.md / database-schema.md
+- rest-api-spec.md / external-apis.md
+- testing-strategy.md
+
+## Outputs
+
+- Updated architecture reference under `docs/architecture` aligned to the current codebase
+- Clear notes on constraints, debt, and risky areas
+- Links to key files and modules for rapid navigation
+
+## Done Criteria
+
+- Architecture docs reflect the current state, not the ideal
+- Sections are navigable and reference real file paths
+- If a PRD exists, impacted areas are highlighted
+- Testing and operations sections state what actually works today

package/core/tasks/execute-checklist.md

@@ -0,0 +1,37 @@
+# execute-checklist
+
+```yaml
+id: execute-checklist
+role: dev
+whenToUse: Run a defined checklist to ensure Definition of Done or role-specific quality criteria are satisfied.
+elicit: true
+outcome: Completed checklist with PASS/FAIL per item and remediation notes
+```
+
+## Objective
+Execute a named checklist (e.g., story-dod-checklist.md) and capture gaps before marking work complete.
+
+## Preconditions
+- Target checklist file exists under `.aigile-core/checklists/`
+- Work item (story/task) is in a state ready for validation
+
+## Steps
+1. Ask user which checklist to execute (suggest defaults based on role).
+2. Load the checklist file content (do not load other files yet).
+3. Present each item as a numbered list and for each:
+   - Ask: PASS, FAIL, or N/A
+   - If FAIL: request remediation plan or immediate fix steps
+4. Summarize failed items and propose concrete next actions.
+5. If all required items PASS, produce a READY-FOR-REVIEW summary including:
+   - Scope validated
+   - Evidence (tests, docs updated)
+   - Remaining risks
+6. Ask user to confirm closure or request further refinement.
+
+## Outputs
+- A structured summary (Checklist Result Table + Next Actions)
+- Optional inline remediation plan if failures present
+
+## Guidance
+- Never silently assume PASS—always confirm.
+- If checklist references artifacts (tests, docs), verify existence or ask user to provide them.

package/core/tasks/explain-story-from-jira.md

@@ -0,0 +1,44 @@
+<!-- BMAD-style story explanation with clear outputs -->
+
+# Dev Task: Explain Story from Jira (by URL or ID)
+
+Produce a crisp, testable explanation of a Jira story/task for reviewers and pair programming.
+
+## Inputs
+
+```yaml
+required:
+  - urlOrId: 'ENG-456' | 'https://your.atlassian.net/browse/ENG-456'
+```
+
+## Process (Sequential)
+
+1. Read the Issue Thoroughly
+  - Title, description, AC, subtasks, links
+2. Clarify Objective and Constraints
+  - Objective in one sentence; list constraints and assumptions
+3. Translate AC → GWT Scenarios
+  - Include at least one negative and one boundary case
+4. Outline Implementation
+  - Files/modules/data model changes; feature flags/configs
+5. Test Approach
+  - Levels (unit/integration/e2e), fixtures, mocks; focus on critical logic
+6. Risks and Open Questions
+  - Identify unknowns; propose mitigations and follow-ups
+
+## Outputs
+
+- One-page brief including: objective, constraints, GWT scenarios, implementation outline, test approach, and open questions
+
+## Examples
+
+- ENG-321 Add rate limiting to API endpoint
+  - Objective: protect backend from bursts without breaking normal usage
+  - GWT: Given N requests/sec ... When threshold exceeded ... Then 429 with Retry-After
+  - Impl: middleware; shared limiter; config thresholds; logs; metrics
+  - Tests: normal flow; throttled flow; headers present; burst with jitter; reset window
+
+## Done Criteria
+
+- Self-contained, test-focused, under ~1 page
+- Includes at least one negative-path scenario

package/core/tasks/facilitate-brainstorming-session.md

@@ -0,0 +1,69 @@
+<!-- Inspired by BMAD™ Core style; adapted for AIgile Core Config -->
+
+# Analyst Task: Facilitate Brainstorming Session
+
+## Purpose
+
+Lead an interactive ideation session to generate many options, synthesize themes, and select promising directions. Prioritize facilitation over idea provision—unlock the team's creativity and capture outcomes in a structured document for later decisions.
+
+## Inputs
+
+```yaml
+optional:
+  topic: "What are we brainstorming about?" # default: ask user
+  constraints: ["time", "budget", "compliance"] # default: ask user
+  output_document: true # if true, save to docs/brainstorming-session-results.md
+```
+
+## Prerequisites
+
+- Confirm session timebox (e.g., 45–60 minutes)
+- Confirm participants and roles (facilitator, note-taker if any)
+- Load techniques list if available in project data (e.g., crazy 8s, SCAMPER, six thinking hats)
+
+## Process (Sequential)
+
+1. Session Setup (5 min)
+	- Clarify topic and success criteria (what “good” looks like today)
+	- Confirm constraints: scope, domain, compliance, tech boundaries
+	- Choose a technique path: user-selected, facilitator-recommended, random, or progressive flow
+2. Warm-up (3–5 min)
+	- Light prompt to reduce blank-page effect (e.g., “List 5 wild ideas fast”)
+3. Divergent Generation (15–25 min)
+	- Run one technique at a time; timebox each round
+	- Keep energy high; defer judgment; encourage quantity over quality
+	- Prompt for variations, opposites, combinations
+4. Convergent Synthesis (10–15 min)
+	- Cluster ideas into themes; label groups
+	- Identify patterns, constraints, and dependencies
+5. Prioritization (5–10 min)
+	- Pick 3–5 candidates for deeper exploration using a simple rubric (impact, feasibility, time)
+6. Document Output (rolling)
+	- If output_document is true, capture ideas by technique, themes, and top picks as you go
+
+## Outputs
+
+- Session summary with: topic, participants, techniques used, total ideas, key themes
+- Prioritized shortlist (3–5) with rationale
+- Open questions and follow-ups (owners, next steps)
+- If configured: save to `docs/brainstorming-session-results.md` (path can be adjusted in repo conventions)
+
+## Facilitation Principles
+
+- You are a facilitator—draw ideas out with prompts; only contribute examples to unstick flow
+- Use one technique at a time; switch only when energy dips or goals shift
+- Keep it engaging and timeboxed; narrate transitions explicitly
+- Capture in participants’ own words; avoid re-writing ideas in your voice
+
+## Advanced Prompts (pick as needed)
+
+- Constraint flip: “If we had to do this in 1 week/$1k/with no backend, how?”
+- Perspective shift: “How would a first-time user approach this?”
+- Extremes: “What’s a ‘moonshot’ vs. a 2-day quick win?”
+- Combination: “Combine idea A + C—what emerges?”
+
+## Done Criteria
+
+- Techniques executed as planned (at least 1 divergent + 1 convergent)
+- Shortlist with clear rationale and owners for next steps
+- Document saved or posted back with clear sections (Summary, Techniques, Themes, Shortlist, Follow-ups)

package/core/tasks/figma-audit-design-system.md

@@ -0,0 +1,20 @@
+<!-- BMAD-style DS audit -->
+
+# UI Task: Figma Audit Design System
+
+Audit a Figma design system library for token/component drift and propose fixes.
+
+## Process (Sequential)
+
+1. Inventory
+	- Tokens (color/typography/spacing), components, variants
+2. Detect Drift
+	- Naming inconsistencies, duplicate tokens, variant sprawl
+3. Recommend Fixes
+	- Token naming/grouping, component normalization, deprecation plan
+4. Output
+	- Prioritized fix list with redlines/screenshots
+
+## Outputs
+
+- Audit report and prioritized remediation plan

package/core/tasks/front-end-spec-from-design.md

@@ -0,0 +1,33 @@
+# UX Task: Front-end Spec from Design
+
+uses: [sequentialthinking, context7, figma]
+
+Workflow
+<!-- BMAD-style UX spec creation using AIgile template -->
+
+# UX Task: Front-end Spec from Design
+
+Create a developer-ready front-end specification from Figma designs.
+
+## Inputs
+
+```yaml
+optional:
+  - frameUrl: 'https://www.figma.com/file/xyz?node-id=123'
+```
+
+## Process (Sequential)
+
+1. Extract Component Anatomy and States
+	- Variants, states, interactions, tokens
+2. Specify API
+	- Props/slots/events; accessible names and roles
+3. Layout and Responsiveness
+	- Constraints, breakpoints, fluid/responsive behavior
+4. Output Using Template
+	- Use `core/templates/front-end-spec-tmpl.yaml` to structure content
+
+## Outputs
+
+- Front-end spec draft referencing the template
+  - Links to Figma frames and exported assets (if any)

package/core/tasks/gate.md

@@ -0,0 +1,64 @@
+<!-- Modeled after BMAD qa-gate with AIgile paths -->
+
+# QA Task: Gate Story
+
+Create or update a quality gate decision for a story with clear PASS/CONCERNS/FAIL/WAIVED status and actionable findings.
+
+## Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}'
+  - story_path: '{devStoryLocation}/{epic}.{story}.*.md' # From core-config.yaml
+optional:
+  - story_title: '{title}'
+  - story_slug: '{slug}'
+```
+
+## Process (Sequential)
+
+1. Review Story
+	- Read objective and AC; restate expected behaviors
+	- Verify Dev Agent Record updated and tests passing
+2. Inspect Evidence
+	- Map AC → tests; note gaps or over-testing
+	- Review SonarQube issues related to the change set
+	- Spot NFR concerns (security/perf/reliability/maintainability)
+3. Determine Gate
+	- PASS if AC met and no high-severity issues
+	- CONCERNS for non-blocking gaps or missing P1 tests
+	- FAIL for unmet AC or high-severity risks (security/data loss)
+	- WAIVED only with explicit approval and rationale
+4. Create Gate File
+	- Save to `qa.qaLocation/gates/{epic}.{story}-{slug}.yml`
+	- Use fixed severity scale: low | medium | high
+5. Update Story (QA Results section only)
+	- Append gate status line and brief rationale
+
+## Gate File Schema (minimal)
+
+```yaml
+schema: 1
+story: '{epic}.{story}'
+story_title: '{title}'
+gate: PASS|CONCERNS|FAIL|WAIVED
+status_reason: '1-2 sentence explanation'
+reviewer: 'Quinn (Test Architect)'
+updated: '{ISO-8601 timestamp}'
+top_issues: []
+waiver: { active: false }
+```
+
+## Story Update Snippet
+
+```text
+Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
+```
+
+## Quality Checklist
+
+- [ ] AC mapped to tests; gaps documented
+- [ ] Severity values use only: low/medium/high
+- [ ] NFR concerns captured (security, performance, reliability, maintainability)
+- [ ] Gate file written to configured path
+- [ ] Story updated under QA Results only

package/core/tasks/groom-jira-story.md

@@ -0,0 +1,52 @@
+<!-- Aligns with BMAD review-story approach for clarity and testability -->
+
+# PO Task: Groom Jira Story
+
+Ensure a Jira story is clear, testable, and ready for development with linked context and unambiguous acceptance criteria.
+
+## Inputs
+
+```yaml
+required:
+  - urlOrId: 'ENG-123' | 'https://your.atlassian.net/browse/ENG-123'
+optional:
+  - confluenceLinks: []
+  - relatedIssues: []
+	- savePrompt: true
+```
+
+## Process (Sequential)
+
+1. Clarify Objective
+	- Restate in one sentence: who, what, why
+	- Ensure scope and constraints are explicit (out-of-scope listed)
+2. Author Acceptance Criteria (AC)
+	- Use Given/When/Then
+	- Include at least: happy path, negative, and boundary case
+3. Link Context
+	- Confluence specs, designs, architecture references
+	- Dependencies and blockers (and their owners)
+4. Ready-for-Dev Check
+	- Estimable? Testable? Valuable? Small enough? No major unknowns?
+	- Labels/components set; Definition of Ready satisfied
+5. Status Update
+	- Move to “Ready for Dev” when all criteria are met
+	- If Jira write is not available, provide the updated story markdown for manual update
+
+## Outputs
+
+- Updated Jira story or markdown with:
+  - Clear objective
+  - AC in GWT format
+  - Links (Confluence/design/related)
+  - Labels/components/estimate (if used)
+  - Status: Ready for Dev (if applicable)
+	- Optional: local file saved under docs/stories/story-{key-or-slug}.md
+
+## Quality Checklist
+
+- [ ] Objective is crisp and user-focused
+- [ ] AC cover happy, negative, and boundary
+- [ ] Links to required context are present
+- [ ] Dependencies identified with owners
+- [ ] Meets Definition of Ready

package/core/tasks/help.md

@@ -0,0 +1,27 @@
+# Dev Task: Help
+
+Use these commands with the Dev agent:
+
+- implement-story-from-jira {urlOrId}
+  - Implement a Jira issue with a test-first, small-steps plan.
+- explain-story-from-jira {urlOrId}
+  - Produce a crisp, testable summary and plan for the issue.
+- implement-work-item {freeform}
+  - Implement a pasted mini-story/task with acceptance criteria.
+- check-story-implemented {urlOrId}
+  - Assess completeness vs AC; report gaps and next actions.
+- implement-unit-tests {pathOrScope}
+  - Add or improve unit tests in a target module.
+- review-qa
+  - Apply QA feedback efficiently and safely.
+- develop-story
+  - Execute an approved story end-to-end with validations.
+- run-tests
+  - Run lint and tests; summarize failures and next steps.
+- exit
+  - End the session.
+
+Tips
+- Start with sequentialthinking for a short plan.
+- Update story records under docs/stories when working on Jira items.
+- Prefer smallest change that satisfies AC; commit in small chunks.

package/core/tasks/implement-freeform-work-item.md

@@ -0,0 +1,30 @@
+# Dev Task: Implement Work Item (Freeform)
+
+Intent
+- Implement a user-provided task/mini-story pasted into chat, using a plan-first approach.
+
+Inputs
+- freeform: plain text containing objective, acceptance, constraints (if any)
+
+Outputs
+- Code + tests implementing the request
+- Short summary: changes made, risks, test results
+
+Workflow
+1) Parse the input
+   - Extract: objective, acceptance, constraints, done criteria
+2) Plan with sequentialthinking
+   - Bullet tasks (5–9), impacted files, tests, risks, rollback
+3) Implement in small steps with tests
+4) Validate (lint, unit, integration if relevant)
+5) Summarize results and next steps
+
+Checklists
+- Inputs validated and sanitized where applicable
+- Backward-compat maintained
+- Logging + error handling included
+- Tests cover happy path and 1–2 edge cases
+
+Examples
+- "Refactor date utility to add toZonedTime() with IANA support; AC: DST safe, UTC fallback"
+- "Add feature flag for new pricing calc; AC: disabled by default, config-driven"

package/core/tasks/implement-story-from-jira.md

@@ -0,0 +1,63 @@
+# Dev Task: Implement Story from Jira (by URL or ID)
+
+Intent
+- Implement a Jira issue (story/task/bug) safely in small steps with tests, based on a key like ENG-123 or a full URL.
+
+Prerequisites
+- Atlassian MCP configured (jira scope). If not, paste the full issue body here.
+- Local build is green; tests pass before starting (establish baseline).
+
+Inputs
+- urlOrId: Jira key (e.g., ENG-123) or full Jira URL.
+
+Outputs
+- Code and tests committed in small, reviewable chunks.
+- Updated story record at docs/stories/{project}/{key}.md containing:
+  - Dev Agent Record (date, approach, decisions, trade-offs)
+  - File List (added/changed/removed)
+  - Test Summary (scenarios covered; notable edge cases)
+- PR preparation notes summarizing what changed and why.
+
+Workflow
+1) Fetch and read
+   - Retrieve: title, description, Acceptance Criteria (AC), subtasks, links (Confluence/PRs/design).
+   - Note ambiguities; suggest defaults and confirm with PO/PM if risky.
+2) Translate AC → executable checks
+   - Convert each AC to Given-When-Then (GWT) scenarios.
+   - Identify non-functional constraints (perf, security, accessibility, i18n, durability).
+3) Plan with sequentialthinking (5–9 bullets)
+   - Minimal tasks, impacted files, data model changes.
+   - Risk list and rollback path; validation steps (lint, unit, integration, exploratory).
+4) Implement in slices
+   - For each slice: code → tests → run → fix → commit with clear message.
+   - Keep change radius small; avoid refactors unless enabling the story.
+5) Validate
+   - Run focused tests, then broader suite; verify AC coverage.
+   - Add negative and boundary tests; verify logging and error handling.
+6) Update story record and summarize
+   - Record decisions, trade-offs, follow-ups; link commits/PR.
+
+Checklists
+- AC mapped 1:1 to tests or combined suites
+- Input validation and error paths covered
+- Feature flag/config toggles for risky changes
+- Logs at correct levels; no secrets in logs
+- Docs updated (README/migrations if needed)
+
+Examples
+- Example: ENG-123 Retry with jitter for Orders client
+  - AC: up to 5 attempts; cap 2s; warn on final failure
+  - Plan: introduce retry helper; inject into client; unit-test helper; integration-test client
+  - Edges: non-retryable codes; cancellations; timeouts
+- Example: ENG-987 SKU search filter
+  - AC: prefix search; case-insensitive; limit 50
+  - Plan: repo method; index; tests for case/prefix/pagination
+
+Done Criteria
+- All AC satisfied by passing tests; no lint/type errors; story record updated
+
+---
+
+Command usage
+- implement-story-from-jira ENG-123
+- implement-story-from-jira https://yourcompany.atlassian.net/browse/ENG-123

package/core/tasks/implement-unit-tests.md

@@ -0,0 +1,45 @@
+<!-- BMAD-style unit test implementation guidance -->
+
+# Dev Task: Implement Unit Tests
+
+Add or improve unit tests for a module/feature to lock behavior and reduce regressions.
+
+## Inputs
+
+```yaml
+required:
+  - pathOrScope: 'src/module' | 'src/utils/date.ts'
+```
+
+## Process (Sequential)
+
+1. Identify Behaviors and Edge Cases
+   - Enumerate Given/When/Then scenarios and invariants
+2. Follow Project Conventions
+   - Test framework, directory structure, naming
+3. Write Tests
+   - Happy path, at least one negative, boundary cases
+   - Stub/mock external services; keep deterministic
+4. Run and Iterate
+   - Make tests fast; avoid global state; ensure isolation
+5. Coverage as a Guide
+   - Prioritize critical logic over line count
+6. Document Results
+   - Short summary of covered scenarios and intentional exclusions
+
+## Outputs
+
+- New/updated tests with passing state
+- Brief test plan summary for story or module docs
+
+## Checklist
+
+- [ ] Deterministic (no network/time flakiness; use fakes)
+- [ ] Clear AAA structure and naming
+- [ ] Fast execution; no leaks
+- [ ] Edge cases included
+
+## Examples
+
+- price-module → rounding, currency edge cases, invalid inputs
+- orders-service → retry backoff and cancellation

package/core/tasks/market-research-from-context7.md

@@ -0,0 +1,37 @@
+<!-- BMAD-style research framing; runs on AIgile context tools -->
+
+# Analyst Task: Market Research from Context7
+
+Create a focused market research brief using internal knowledge bases and trusted sources, with clear questions, findings, and next steps.
+
+## Inputs
+
+```yaml
+optional:
+  - focus: 'competitive landscape' | 'market sizing' | 'pricing' | 'trends'
+  - products: ['Competitor A', 'Competitor B']
+  - timeframe: 'last 12 months'
+  - regions: ['NA', 'EU']
+```
+
+## Process (Sequential)
+
+1. Define Objectives and Questions
+	- Clarify scope, key decisions, and success criteria
+2. Collect Evidence
+	- Query context7 KBs; capture source links and dates
+	- Prefer credible sources; note gaps or conflicting data
+3. Analyze and Synthesize
+	- Summarize trends, competitor positions, and market signals
+	- Use simple comparison matrices where helpful
+4. Draft Brief
+	- Executive summary, key findings, implications
+	- Risks/unknowns and areas for further research
+5. Review and Next Steps
+	- Propose decisions to be informed; suggest follow-up research or validation
+
+## Outputs
+
+- Market research brief with sources and dates
+- Comparison matrix (if applicable)
+- Open questions and recommended next actions

package/core/tasks/review-story.md

@@ -0,0 +1,30 @@
+# review-story
+
+```yaml
+id: review-story
+role: qa
+whenToUse: Perform QA-oriented review of an implemented story before or during formal testing.
+elicit: false
+outcome: PASS/NEEDS-WORK assessment with concrete gaps.
+```
+
+## Objective
+Evaluate whether an implemented story meets acceptance, quality, and risk criteria.
+
+## Steps
+1. Request story identifier or content if not already loaded.
+2. Identify implemented changes (scan file list, code diffs if accessible, or ask user).
+3. Map Acceptance Criteria → Observed Implementation / Tests.
+4. Check negative/error paths & edge cases.
+5. Evaluate non-functional aspects (performance, logging, security hints) if relevant.
+6. Produce findings table: Criterion | Status | Notes.
+7. Provide overall recommendation with prioritized fix suggestions.
+
+## Outputs
+- Findings table
+- Recommendation (PASS or NEEDS-WORK)
+- Top 3 risk or quality concerns
+
+## Guidance
+- Be evidence-driven; avoid generic statements.
+- Suggest smallest viable fixes.

package/core/tasks/sonarqube-hotspot-review.md

@@ -0,0 +1,39 @@
+<!-- BMAD-style SonarQube hotspot triage -->
+
+# QA Task: SonarQube Hotspot Review
+
+Triage SonarQube security hotspots and code issues related to the change set, classify severity, and propose actionable fixes.
+
+## Inputs
+
+```yaml
+optional:
+  - scope: 'repo|module|path' # default: changed files only
+  - branch: 'current'
+```
+
+## Process (Sequential)
+
+1. Select Scope
+	- Prefer changed files in current branch; expand if needed
+2. Retrieve Hotspots and Issues
+	- Filter to security hotspots and high-impact code smells
+3. Classify Findings
+	- Use fixed severity: low | medium | high
+	- Note CWE/OWASP mapping if available
+4. Recommend Actions
+	- Immediate fixes vs follow-up tickets with owners
+	- Link to files and lines; suggest tests if applicable
+5. Output Summary
+	- Provide concise report and optional gate-ready snippet
+
+## Outputs
+
+- Hotspot review report: findings by severity, recommended actions, owners
+- Optional gate snippet for inclusion under `top_issues` in QA Gate file
+
+## Severity Scale (Fixed)
+
+- low: minor improvement, not risky
+- medium: should fix soon, potential risk area
+- high: critical security or correctness risk; blocks release unless waived