@mark-gozner/aigile-method 0.4.5

package/core/checklists/story-draft-checklist.md

@@ -0,0 +1,153 @@
+# Story Draft Checklist
+
+The Product Owner should use this checklist to validate that each story contains sufficient context for a developer agent to implement it successfully, while assuming the dev agent has reasonable capabilities to figure things out.
+
+[[LLM: INITIALIZATION INSTRUCTIONS - STORY DRAFT VALIDATION
+
+Before proceeding with this checklist, ensure you have access to:
+
+1. The story document being validated (usually in docs/stories/ or provided directly)
+2. The parent epic context
+3. Any referenced architecture or design documents
+4. Previous related stories if this builds on prior work
+
+IMPORTANT: This checklist validates individual stories BEFORE implementation begins.
+
+VALIDATION PRINCIPLES:
+
+1. Clarity - A developer should understand WHAT to build
+2. Context - WHY this is being built and how it fits
+3. Guidance - Key technical decisions and patterns to follow
+4. Testability - How to verify the implementation works
+5. Self-Contained - Most info needed is in the story itself
+
+REMEMBER: We assume competent developer agents who can:
+
+- Research documentation and codebases
+- Make reasonable technical decisions
+- Follow established patterns
+- Ask for clarification when truly stuck
+
+We're checking for SUFFICIENT guidance, not exhaustive detail.]]
+
+## 1. GOAL & CONTEXT CLARITY
+
+[[LLM: Without clear goals, developers build the wrong thing. Verify:
+
+1. The story states WHAT functionality to implement
+2. The business value or user benefit is clear
+3. How this fits into the larger epic/product is explained
+4. Dependencies are explicit ("requires Story X to be complete")
+5. Success looks like something specific, not vague]]
+
+- [ ] Story goal/purpose is clearly stated
+- [ ] Relationship to epic goals is evident
+- [ ] How the story fits into overall system flow is explained
+- [ ] Dependencies on previous stories are identified (if applicable)
+- [ ] Business context and value are clear
+
+## 2. TECHNICAL IMPLEMENTATION GUIDANCE
+
+[[LLM: Developers need enough technical context to start coding. Check:
+
+1. Key files/components to create or modify are mentioned
+2. Technology choices are specified where non-obvious
+3. Integration points with existing code are identified
+4. Data models or API contracts are defined or referenced
+5. Non-standard patterns or exceptions are called out
+
+Note: We don't need every file listed - just the important ones.]]
+
+- [ ] Key files to create/modify are identified (not necessarily exhaustive)
+- [ ] Technologies specifically needed for this story are mentioned
+- [ ] Critical APIs or interfaces are sufficiently described
+- [ ] Necessary data models or structures are referenced
+- [ ] Required environment variables are listed (if applicable)
+- [ ] Any exceptions to standard coding patterns are noted
+
+## 3. REFERENCE EFFECTIVENESS
+
+[[LLM: References should help, not create a treasure hunt. Ensure:
+
+1. References point to specific sections, not whole documents
+2. The relevance of each reference is explained
+3. Critical information is summarized in the story
+4. References are accessible (not broken links)
+5. Previous story context is summarized if needed]]
+
+- [ ] References to external documents point to specific relevant sections
+- [ ] Critical information from previous stories is summarized (not just referenced)
+- [ ] Context is provided for why references are relevant
+- [ ] References use consistent format (e.g., `docs/filename.md#section`)
+
+## 4. SELF-CONTAINMENT ASSESSMENT
+
+[[LLM: Stories should be mostly self-contained to avoid context switching. Verify:
+
+1. Core requirements are in the story, not just in references
+2. Domain terms are explained or obvious from context
+3. Assumptions are stated explicitly
+4. Edge cases are mentioned (even if deferred)
+5. The story could be understood without reading 10 other documents]]
+
+- [ ] Core information needed is included (not overly reliant on external docs)
+- [ ] Implicit assumptions are made explicit
+- [ ] Domain-specific terms or concepts are explained
+- [ ] Edge cases or error scenarios are addressed
+
+## 5. TESTING GUIDANCE
+
+[[LLM: Testing ensures the implementation actually works. Check:
+
+1. Test approach is specified (unit, integration, e2e)
+2. Key test scenarios are listed
+3. Success criteria are measurable
+4. Special test considerations are noted
+5. Acceptance criteria in the story are testable]]
+
+- [ ] Required testing approach is outlined
+- [ ] Key test scenarios are identified
+- [ ] Success criteria are defined
+- [ ] Special testing considerations are noted (if applicable)
+
+## VALIDATION RESULT
+
+[[LLM: FINAL STORY VALIDATION REPORT
+
+Generate a concise validation report:
+
+1. Quick Summary
+   - Story readiness: READY / NEEDS REVISION / BLOCKED
+   - Clarity score (1-10)
+   - Major gaps identified
+
+2. Fill in the validation table with:
+   - PASS: Requirements clearly met
+   - PARTIAL: Some gaps but workable
+   - FAIL: Critical information missing
+
+3. Specific Issues (if any)
+   - List concrete problems to fix
+   - Suggest specific improvements
+   - Identify any blocking dependencies
+
+4. Developer Perspective
+   - Could YOU implement this story as written?
+   - What questions would you have?
+   - What might cause delays or rework?
+
+Be pragmatic - perfect documentation doesn't exist, but it must be enough to provide the extreme context a dev agent needs to get the work down and not create a mess.]]
+
+| Category                             | Status | Issues |
+| ------------------------------------ | ------ | ------ |
+| 1. Goal & Context Clarity            | _TBD_  |        |
+| 2. Technical Implementation Guidance | _TBD_  |        |
+| 3. Reference Effectiveness           | _TBD_  |        |
+| 4. Self-Containment Assessment       | _TBD_  |        |
+| 5. Testing Guidance                  | _TBD_  |        |
+
+**Final Assessment:**
+
+- READY: The story provides sufficient context for implementation
+- NEEDS REVISION: The story requires updates (see issues)
+- BLOCKED: External information required (specify what information)

package/core/core-config.yaml

@@ -0,0 +1,22 @@
+markdownExploder: true
+qa:
+  qaLocation: docs/qa
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v1
+  prdSharded: true
+  prdShardedLocation: docs/prd
+  epicFilePattern: epic-{n}*.md
+architecture:
+  architectureFile: docs/architecture.md
+  architectureVersion: v1
+  architectureSharded: true
+  architectureShardedLocation: docs/architecture
+customTechnicalDocuments: null
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/source-tree.md
+devDebugLog: .ai/debug-log.md
+devStoryLocation: docs/stories
+slashPrefix: aigile

package/core/data/aigile-kb.md

@@ -0,0 +1,112 @@
+<!-- Powered by AIgile™ Core -->
+
+# AIgile Knowledge Base
+
+## Overview
+
+AIgile (AI-assisted Agile Development Method) provides a lean, role-focused agent system, reusable tasks/templates/checklists, and MCP-enabled integrations to deliver software with clear handoffs and strong quality gates.
+
+### Key Features
+
+- Role-specialized agents (Analyst, PM, PO, Architect, Dev, QA, UX/UI, SM)
+- Reusable resources: tasks, templates, checklists, and data
+- IDE-first flow with optional web bundle for planning
+- MCP-ready: GitHub, Atlassian, SonarQube, Playwright, Memory, Sequential Thinking, Context7
+- Clean dependency mapping for precise, minimal context
+
+### When to Use AIgile
+
+- Greenfield projects: PRD → Architecture → Stories → Implementation
+- Brownfield work: Document current system → Focused epics/stories → Incremental improvements
+- Team collaboration: Clear per-role workflows and quality checks
+
+## How AIgile Works
+
+### Core Method
+
+You direct specialized agents through executable tasks. Each agent focuses on its discipline, uses declared dependencies only when needed, and hands off work cleanly to the next role.
+
+1. You set the goal and provide decisions.
+2. Agents execute via tasks and checklists, loading only referenced dependencies.
+3. Clean, fresh chats between roles preserve context quality.
+
+### Two-Phase Approach
+
+- Planning (often Web UI): Create PRD/Architecture efficiently; multi-agent ideation and research.
+- Development (IDE): Shard docs, implement stories sequentially, validate with QA before Done.
+
+### Development Loop
+
+```
+1. SM → create next story from sharded docs
+2. You review/approve
+3. Dev → implement story with tests
+4. QA → review and validate
+5. You verify completion
+6. Repeat
+```
+
+### Why This Works
+
+- Role clarity and specialization
+- Minimal necessary context at each step
+- Strong gates and explicit acceptance criteria
+
+## Getting Started
+
+- Web bundle: use `dist/teams/team-company.txt` in large-context web models for planning.
+- IDE install: `aigile install` to copy `.aigile-core`, generate chatmodes, and optional MCP configuration.
+
+Required docs: save planning outputs to `docs/prd.md` and `docs/architecture.md`; shard to `docs/prd/` and `docs/architecture/` for development.
+
+## Core Configuration
+
+`core/core-config.yaml` defines where docs live and what the dev agent should always load (devLoadAlwaysFiles). It enables gradual adoption and custom layouts.
+
+## Reusable Resources
+
+- Templates: PRD, architecture, story, QA gate, front-end spec
+- Tasks: shard-doc, create-next-story, implement-story-from-jira, test-design, gate
+- Checklists: story DoD, PO master, architect review, change checklist
+- Data: brainstorming techniques, elicitation methods, technical preferences, test levels, test priorities
+
+## Agent System (Quick Reference)
+
+| Agent | Primary Functions |
+| --- | --- |
+| analyst | brainstorming, research, project documentation |
+| pm | PRD creation, backlog sync, planning |
+| po | story creation, grooming, validation |
+| architect | architecture design/review, ADRs |
+| dev | story implementation, tests, code quality |
+| qa | test design, quality gates, E2E validation |
+| ux/ui | research, journey mapping, design system compliance |
+| sm | story creation, facilitation |
+
+## IDE Usage Principles
+
+- Use fresh chats when switching roles.
+- Only load dependency files during task execution.
+- Tasks with elicit=true require user interaction.
+- Keep Dev agent lean; planning agents can be richer in web contexts.
+
+## Brownfield Guidance (Condensed)
+
+- Document first (analyst document-project), then PRD/architecture.
+- Shard docs; implement one story at a time.
+- Emphasize compatibility, migration, and risk mitigation; prefer incremental rollout.
+
+## Success Tips
+
+- Keep the technical preferences current.
+- Tie AC to test levels and priorities.
+- Maintain decision logs and risks for visibility.
+- Prefer smallest viable change; validate early.
+
+## See Also
+
+- `core/data/technical-preferences.md`
+- `core/data/test-levels-framework.md`
+- `core/data/test-priorities-matrix.md`
+- `core/data/brainstorming-techniques.md`
+- `core/data/elicitation-methods.md`

package/core/data/brainstorming-techniques.md

@@ -0,0 +1,73 @@
+# Brainstorming Techniques (Company)
+
+Clear, time-boxed facilitation patterns your Analyst, PM/PO, and Architect can run. Always capture raw ideas and synthesize outcomes into decisions, risks, and next steps.
+
+## How to pick a technique
+- Use Round-robin when you need equal participation with low facilitation overhead.
+- Use Crazy 8s to diverge quickly on UI/flow concepts or solution shapes.
+- Use SCAMPER to systematically transform an existing idea/process.
+- Use Assumption Busting to de-risk bold initiatives or legacy rewrites.
+- Use Worst Idea Wins to surface hidden risks and anti-patterns playfully.
+
+## Techniques (numbered for quick reference)
+1) Round-robin ideation
+	 - Goal: Ensure every voice contributes at least one idea per round.
+	 - Timebox: 10–20 minutes, 2–3 rounds.
+	 - Steps:
+		 1. State the prompt and constraints in one sentence.
+		 2. Go around the group one by one; each person shares 1 idea (max 30s).
+		 3. Write all ideas verbatim; no discussion or critique.
+		 4. After rounds, cluster similar ideas and dot-vote top 3.
+	 - Outputs: Ranked idea list, clusters/themes, top 3 for refinement.
+
+2) Crazy 8s (adapted for product/UX and flows)
+	 - Goal: Rapid divergence; 8 variations in 8 minutes per person.
+	 - Timebox: 10–15 minutes ideation + 10 minutes share-out.
+	 - Steps:
+		 1. Provide the scenario (e.g., onboarding flow, dashboard layout).
+		 2. Each participant sketches 8 variations (1 per minute). Bulleted text is fine if sketching isn’t feasible.
+		 3. 60–90 seconds per person to present their strongest 1–2 variants.
+		 4. Collect patterns and shortlist 2–3 concepts for prototype/spike.
+	 - Outputs: Photo/scan of variations, shortlist of concepts, next prototype task.
+
+3) SCAMPER prompts (adapted)
+	 - Substitute, Combine, Adapt, Modify/Magnify/Minify, Put to other uses, Eliminate, Reverse/Rearrange.
+	 - Timebox: 20–30 minutes.
+	 - Steps:
+		 1. Take a current solution or process.
+		 2. Walk through each SCAMPER lens; generate at least 1 idea per lens.
+		 3. Mark ideas that reduce complexity/cost or increase user value.
+	 - Outputs: SCAMPER idea set with annotations on impact/effort.
+
+4) Assumption busting
+	 - Goal: Identify and test risky assumptions early.
+	 - Timebox: 25–40 minutes.
+	 - Steps:
+		 1. List top 10 assumptions underpinning the idea or system.
+		 2. Score each assumption by impact if wrong (High/Med/Low) and confidence (High/Med/Low).
+		 3. Target High-impact, Low-confidence assumptions for spikes/experiments.
+	 - Outputs: Assumption register with experiment/spike backlog.
+
+5) Worst idea wins (to surface risks)
+	 - Goal: Elicit failure modes and anti-patterns safely.
+	 - Timebox: 15–25 minutes.
+	 - Steps:
+		 1. Prompt: “What’s the WORST way to solve this?” Encourage humor.
+		 2. Extract implicit risks/anti-patterns from the worst ideas.
+		 3. Convert to mitigations, guardrails, or acceptance criteria.
+	 - Outputs: Risk list with mitigations and DoD/AC updates.
+
+## Facilitator checklist
+- Clarify the single prompt and constraints.
+- Enforce timeboxes strictly; keep critique out during divergence.
+- Capture everything in the raw; synthesize only after divergence.
+- End with decisions, named owners, and next steps.
+
+## Anti-patterns to avoid
+- Open-ended sessions without a timebox or a clear prompt.
+- Premature critique shutting down contributions.
+- No synthesis or next steps.
+
+## References in this repository
+- Use with Analyst commands: brainstorm, create-project-brief, perform-market-research.
+- See also: `core/data/elicitation-methods.md` for follow-up interviews/workshops.

package/core/data/elicitation-methods.md

@@ -0,0 +1,42 @@
+# Elicitation Methods (Company)
+
+Field-proven techniques to discover and refine requirements. Pick the lightest method that answers the question; combine as needed.
+
+## 1) Stakeholder interviews
+- Use when: Clarifying goals, constraints, success metrics, or hidden requirements.
+- Preparation: Interview guide with top 8–12 questions; consent to record; target roles.
+- Steps:
+	1. Open with outcomes and timebox; ask open questions; dig into “why” and “how often”.
+	2. Capture quotes and facts; flag assumptions; ask for examples/artifacts.
+	3. Close with summary, gaps, and follow-ups.
+- Outputs: Interview notes, risks/assumptions list, decisions and open questions.
+
+## 2) Contextual inquiry (on-the-job observation)
+- Use when: Understanding real workflows, tools, and blockers.
+- Steps: Observe tasks, ask “think aloud”, capture artifacts/screens, time pain points.
+- Outputs: As-is workflow, pain points, opportunities, and time-to-task metrics.
+
+## 3) Journey mapping
+- Use when: Visualizing end-to-end user experience across touchpoints.
+- Steps: Define persona, stages, actions, feelings, pain points, opportunities.
+- Outputs: Journey map with prioritized opportunities and hypotheses.
+
+## 4) Prototyping feedback
+- Use when: Testing concepts cheaply before committing.
+- Steps: Prepare clickable or paper prototype; define tasks; observe success/struggle.
+- Outputs: Findings matrix (what worked/struggled), design decisions, next prototype.
+
+## 5) Requirements workshops
+- Use when: Aligning on scope, AC, and definitions across multiple stakeholders.
+- Steps: Timebox; start with goals; draft user stories; define AC using GWT; dot-vote.
+- Outputs: Prioritized stories, AC, open questions, and decision log.
+
+## Artifacts to produce
+- Decision log entries
+- Risks and assumptions
+- User stories with AC (GWT)
+- Updated PRD sections
+
+## Cross-references in this repository
+- Pair with `core/data/brainstorming-techniques.md` for ideation before/after.
+- Use with PO/Analyst tasks: create-next-story, groom-jira-story.

package/core/data/technical-preferences.md

@@ -0,0 +1,52 @@
+# Technical Preferences (Organization Profile)
+
+Purpose: a single source of truth for default technology choices, standards, and guardrails. Agents use this to bias recommendations and templates. Teams may override with project-specific addenda.
+
+Update policy: treat this like a living ADR. Keep concise and actionable.
+
+## Frontend
+- Primary frameworks: [...]
+- Language/TS policy: [...]
+- Testing: Unit (e.g., Vitest/Jest), Component (e.g., Testing Library), E2E (e.g., Playwright)
+- Documentation: Storybook/MDX preferred; architecture decisions recorded under docs/architecture.
+- Accessibility: WCAG 2.2 AA baseline; axe checks in CI.
+
+## Backend
+- Languages/runtimes: [...]
+- Frameworks: [...]
+- Service style: Prefer modular monolith → move to microservices when justified by scale/team topology.
+- API: REST first; GraphQL by exception (document rationale); gRPC for internal high-throughput services.
+- AuthN/Z: Centralized via SSO/IAM; zero trust principles.
+
+## Data
+- Primary databases: [...]
+- Caching/message bus: [...]
+- Object storage: [...]
+- Migration/versioning: [...]
+- Backup/restore objectives: RPO/RTO targets [...]
+
+## CI/CD
+- CI: [...]
+- Strategy: trunk-based with feature flags; short-lived branches; protected main.
+- Quality gates: lint, unit, integration, security scan before merge; release validation suite before deploy.
+
+## Cloud & Infra
+- Target environments: [...]
+- IaC: [...]; environments as code; immutable artifacts.
+- Secrets: central secret manager; never in repo; rotate quarterly.
+
+## Observability
+- Logging/metrics/tracing stack: [...]
+- SLOs/SLIs: define for top user journeys; alert on burn rate.
+
+## Security
+- Baseline: OWASP ASVS Level 2; OWASP Top 10 policy in CI.
+- SSO/IAM: [...]; least privilege; periodic access reviews.
+
+## Anti-patterns to avoid
+- Accidental polyglot without ownership; bespoke frameworks; duplicated CI pipelines per repo.
+
+## How agents use this file
+- Architect: bias solution options and ADRs; reference in architecture-tmpl sections.
+- Dev/QA: reference for test tooling and gates.
+- PO/PM: use to set non-functional acceptance criteria.

package/core/data/test-levels-framework.md

@@ -0,0 +1,43 @@
+# Test Levels Framework (Company)
+
+Establish a shared mental model for test scope and the entry/exit criteria per level.
+
+## Levels
+- Unit: fast (<100ms), isolated, logic correctness, mock I/O.
+- Component: UI or service component in isolation with fakes.
+- Integration: contracts across modules/services and persistence.
+- E2E: critical user journeys across the stack.
+- Non-functional: performance, security, reliability, accessibility.
+- Release validation: smoke checks and rollback readiness post-deploy.
+
+## Selection criteria
+- Risk: High-risk changes demand broader coverage (integration/E2E).
+- Visibility: User-facing/critical flows need E2E checks.
+- Coupling: Tightly coupled modules benefit from integration tests.
+- Cost: Prefer unit/component until risk justifies higher levels.
+
+## Entry/Exit (per level)
+- Unit
+	- Entry: functions/classes with defined behavior.
+	- Exit: branches and edge cases covered; no external I/O.
+- Integration
+	- Entry: APIs/contracts between modules or DB access present.
+	- Exit: happy path + 2 failure modes; DB migrations verified.
+- E2E
+	- Entry: stable UI/API endpoints and data; flake budget defined.
+	- Exit: top journeys pass; screenshots/traces captured.
+- Non-functional
+	- Entry: target SLO/SLI, workload profile, and environment ready.
+	- Exit: results documented vs baseline; actions filed for regressions.
+- Release validation
+	- Entry: artifact deployed to staging/prod; feature flags configured.
+	- Exit: smoke suite pass; rollback plan verified.
+
+## Example mapping
+- Change: pricing algorithm logic → Unit + Integration (pricing service ↔ DB).
+- Change: login UI → Component + E2E (happy path + lockout edge case).
+- Change: DB migration → Integration + Release validation.
+
+## References in this repository
+- Use with QA tasks: test-design, gate, verify-jira-story-e2e.
+- Use with Dev tasks: run-tests, implement-unit-tests.

package/core/data/test-priorities-matrix.md

@@ -0,0 +1,26 @@
+# Test Priorities Matrix (Company)
+
+Prioritize what to test first by Risk = Probability × Impact. Default heuristics below; calibrate per project.
+
+## Priority bands
+- P0 (Blocker): Critical path breakage, security exposure, data loss, compliance.
+- P1 (High): High-usage features, SLA/SLO-affecting issues, money flows.
+- P2 (Medium): Secondary flows, uncommon states, degraded UX.
+- P3 (Low): Cosmetic issues, low-usage admin screens.
+
+## Quick scoring
+- Probability: 1 (unlikely) – 5 (very likely) considering change area, churn, complexity.
+- Impact: 1 (minimal) – 5 (severe) considering user, financial, compliance, ops.
+- Risk score = P × I. Map 20–25 → P0, 12–19 → P1, 6–11 → P2, 1–5 → P3.
+
+## How to apply in a story
+1. List scenarios (happy path, alt paths, error states).
+2. Score each scenario; pick top-3 by risk for immediate coverage.
+3. Map P0/P1 to E2E or integration; P2 to component/unit; P3 opportunistic.
+4. Record rationale in story test notes; align with test-levels-framework.
+
+## Anti-patterns
+- Equal priority for all tests; E2E-only mindset; skipping risk rationale.
+
+## References in this repository
+- Use with QA tasks: test-design, gate; Dev: run-tests, implement-unit-tests.