agile-context-engineering 0.1.0 → 0.2.0

package/agile-context-engineering/templates/wiki/testing-framework.xml

@@ -0,0 +1,283 @@
+<!-- Credits: Testing template content adapted from GSD (Get Shit Done) by @raisiqueira -->
+<!-- Original source: .gsd/get-shit-done/templates/codebase/testing.md -->
+
+<testing-framework>
+    <purpose>
+        Template for `.docs/wiki/testing-framework.md` — captures test framework, patterns, and
+        conventions for the project. Answers "How do I write and run tests that match existing patterns?"
+
+        **Purpose:** Document how tests are written and run. Guide for adding tests that match
+        existing patterns.
+    </purpose>
+
+    <template>
+        <test-framework>
+            ## Test Framework
+
+            **Runner:**
+            - [Framework: e.g., "Jest 29.x", "Vitest 1.x"]
+            - [Config: e.g., "jest.config.js in project root"]
+
+            **Assertion Library:**
+            - [Library: e.g., "built-in expect", "chai"]
+            - [Matchers: e.g., "toBe, toEqual, toThrow"]
+
+            **Run Commands:**
+            ```bash
+            [e.g., "npm test" or "npm run test"]              # Run all tests
+            [e.g., "npm test -- --watch"]                     # Watch mode
+            [e.g., "npm test -- path/to/file.test.ts"]       # Single file
+            [e.g., "npm run test:coverage"]                   # Coverage report
+            ```
+        </test-framework>
+
+        <test-file-organization>
+            ## Test File Organization
+
+            **Location:**
+            - [Pattern: e.g., "*.test.ts alongside source files"]
+            - [Alternative: e.g., "__tests__/ directory" or "separate tests/ tree"]
+
+            **Naming:**
+            - [Unit tests: e.g., "module-name.test.ts"]
+            - [Integration: e.g., "feature-name.integration.test.ts"]
+            - [E2E: e.g., "user-flow.e2e.test.ts"]
+
+            **Structure:**
+            ```
+            [Show actual directory pattern, e.g.:
+            src/
+              lib/
+                utils.ts
+                utils.test.ts
+              services/
+                user-service.ts
+                user-service.test.ts
+            ]
+            ```
+        </test-file-organization>
+
+        <test-structure>
+            ## Test Structure
+
+            **Suite Organization:**
+            ```typescript
+            [Show actual pattern used, e.g.:
+
+            describe('ModuleName', () => {
+              describe('functionName', () => {
+                it('should handle success case', () => {
+                  // arrange
+                  // act
+                  // assert
+                });
+
+                it('should handle error case', () => {
+                  // test code
+                });
+              });
+            });
+            ]
+            ```
+
+            **Patterns:**
+            - [Setup: e.g., "beforeEach for shared setup, avoid beforeAll"]
+            - [Teardown: e.g., "afterEach to clean up, restore mocks"]
+            - [Structure: e.g., "arrange/act/assert pattern required"]
+        </test-structure>
+
+        <mocking>
+            ## Mocking
+
+            **Framework:**
+            - [Tool: e.g., "Jest built-in mocking", "Vitest vi", "Sinon"]
+            - [Import mocking: e.g., "vi.mock() at top of file"]
+
+            **Patterns:**
+            ```typescript
+            [Show actual mocking pattern, e.g.:
+
+            // Mock external dependency
+            vi.mock('./external-service', () => ({
+              fetchData: vi.fn()
+            }));
+
+            // Mock in test
+            const mockFetch = vi.mocked(fetchData);
+            mockFetch.mockResolvedValue({ data: 'test' });
+            ]
+            ```
+
+            **What to Mock:**
+            - [e.g., "External APIs, file system, database"]
+            - [e.g., "Time/dates (use vi.useFakeTimers)"]
+            - [e.g., "Network calls (use mock fetch)"]
+
+            **What NOT to Mock:**
+            - [e.g., "Pure functions, utilities"]
+            - [e.g., "Internal business logic"]
+        </mocking>
+
+        <fixtures-and-factories>
+            ## Fixtures and Factories
+
+            **Test Data:**
+            ```typescript
+            [Show pattern for creating test data, e.g.:
+
+            // Factory pattern
+            function createTestUser(overrides?: Partial&lt;User&gt;): User {
+              return {
+                id: 'test-id',
+                name: 'Test User',
+                email: 'test@example.com',
+                ...overrides
+              };
+            }
+
+            // Fixture file
+            // tests/fixtures/users.ts
+            export const mockUsers = [/* ... */];
+            ]
+            ```
+
+            **Location:**
+            - [e.g., "tests/fixtures/ for shared fixtures"]
+            - [e.g., "factory functions in test file or tests/factories/"]
+        </fixtures-and-factories>
+
+        <coverage>
+            ## Coverage
+
+            **Requirements:**
+            - [Target: e.g., "80% line coverage", "no specific target"]
+            - [Enforcement: e.g., "CI blocks &lt;80%", "coverage for awareness only"]
+
+            **Configuration:**
+            - [Tool: e.g., "built-in coverage via --coverage flag"]
+            - [Exclusions: e.g., "exclude *.test.ts, config files"]
+
+            **View Coverage:**
+            ```bash
+            [e.g., "npm run test:coverage"]
+            [e.g., "open coverage/index.html"]
+            ```
+        </coverage>
+
+        <test-types>
+            ## Test Types
+
+            **Unit Tests:**
+            - [Scope: e.g., "test single function/class in isolation"]
+            - [Mocking: e.g., "mock all external dependencies"]
+            - [Speed: e.g., "must run in &lt;1s per test"]
+
+            **Integration Tests:**
+            - [Scope: e.g., "test multiple modules together"]
+            - [Mocking: e.g., "mock external services, use real internal modules"]
+            - [Setup: e.g., "use test database, seed data"]
+
+            **E2E Tests:**
+            - [Framework: e.g., "Playwright for E2E"]
+            - [Scope: e.g., "test full user flows"]
+            - [Location: e.g., "e2e/ directory separate from unit tests"]
+        </test-types>
+
+        <common-patterns>
+            ## Common Patterns
+
+            **Async Testing:**
+            ```typescript
+            [Show pattern, e.g.:
+
+            it('should handle async operation', async () => {
+              const result = await asyncFunction();
+              expect(result).toBe('expected');
+            });
+            ]
+            ```
+
+            **Error Testing:**
+            ```typescript
+            [Show pattern, e.g.:
+
+            it('should throw on invalid input', () => {
+              expect(() => functionCall()).toThrow('error message');
+            });
+
+            // Async error
+            it('should reject on failure', async () => {
+              await expect(asyncCall()).rejects.toThrow('error message');
+            });
+            ]
+            ```
+
+            **Snapshot Testing:**
+            - [Usage: e.g., "for React components only" or "not used"]
+            - [Location: e.g., "__snapshots__/ directory"]
+        </common-patterns>
+    </template>
+
+    <guidelines>
+
+        **What belongs in testing-framework.md:**
+        - Test framework and runner configuration
+        - Test file location and naming patterns
+        - Test structure (describe/it, beforeEach patterns)
+        - Mocking approach and examples
+        - Fixture/factory patterns
+        - Coverage requirements
+        - How to run tests (commands)
+        - Common testing patterns in actual code
+
+        **What does NOT belong here:**
+        - Specific test cases (defer to actual test files)
+        - Technology choices (that's system-architecture.md)
+        - CI/CD setup (that's deployment docs)
+
+        **When filling this template:**
+        - Check package.json scripts for test commands
+        - Find test config file (jest.config.js, vitest.config.ts)
+        - Read 3-5 existing test files to identify patterns
+        - Look for test utilities in tests/ or test-utils/
+        - Check for coverage configuration
+        - Document actual patterns used, not ideal patterns
+
+        **Useful for story planning when:**
+        - Adding new features (write matching tests)
+        - Refactoring (maintain test patterns)
+        - Fixing bugs (add regression tests)
+        - Understanding verification approach
+        - Setting up test infrastructure
+
+        **Analysis approach:**
+        - Check package.json for test framework and scripts
+        - Read test config file for coverage, setup
+        - Examine test file organization (collocated vs separate)
+        - Review 5 test files for patterns (mocking, structure, assertions)
+        - Look for test utilities, fixtures, factories
+        - Note any test types (unit, integration, e2e)
+        - Document commands for running tests
+
+    </guidelines>
+
+    <evolution>
+
+        Update when testing patterns or framework changes.
+
+        **Update triggers:**
+        - Test framework or runner changed (e.g., Jest to Vitest)
+        - Mocking approach changed
+        - New test type introduced (e.g., adding E2E tests)
+        - Coverage requirements changed
+        - Test file organization restructured
+        - New test utilities or factories added
+
+        **NOT an update trigger:**
+        - New test files added following existing patterns
+        - Individual test case additions
+        - Bug fixes in test code
+
+    </evolution>
+
+</testing-framework>

package/agile-context-engineering/utils/questioning.xml

@@ -0,0 +1,111 @@
+<!--
+The contents of this file are taken from GSD project
+All credits go to: https://github.com/gsd-build/get-shit-done
+-->
+<questioning-guide>
+    <purpose>Help the user discover and articulate what they want to build by doing collaborative thinking.</purpose>
+
+    <philosophy>
+        **You are a thinking partner, not an interviewer.**
+        The user often starts from a rough and fuzzy idea. Your job is to help them sharpen it.
+        Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+        Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+    </philosophy>
+
+    <how-to-question>
+        **Start open.** Let them dump their mental model. Don't interrupt with structure.
+        **Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+        **Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+        **Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+        **Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+        **Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+    </how-to-question>
+
+    <question-types>
+        Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+        **Motivation — why this exists:**
+        - "What prompted this?"
+        - "What are you doing today that this replaces?"
+        - "What would you do if this existed?"
+
+        **Concreteness — what it actually is:**
+        - "Walk me through using this"
+        - "You said X — what does that actually look like?"
+        - "Give me an example"
+
+        **Clarification — what they mean:**
+        - "When you say Z, do you mean A or B?"
+        - "You mentioned X — tell me more about that"
+
+        **Success — how you'll know it's working:**
+        - "How will you know this is working?"
+        - "What does done look like?"
+    </question-types>
+
+    <using-askuserquestion-tool>
+
+        Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+        **Good options:**
+        - Interpretations of what they might mean
+        - Specific examples to confirm or deny
+        - Concrete choices that reveal priorities
+
+        **Bad options:**
+        - Generic categories ("Technical", "Business", "Other")
+        - Leading options that presume an answer
+        - Too many options (2-4 is ideal)
+
+        **Example — vague answer:**
+        User says "it should be fast"
+
+        - header: "Fast"
+        - question: "Fast how?"
+        - options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+        **Example — following a thread:**
+        User mentions "frustrated with current tools"
+
+        - header: "Frustration"
+        - question: "What specifically frustrates you?"
+        - options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+    </using-askuserquestion-tool>
+
+    <context-checklist>
+        Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+        - [ ] What they're building (concrete enough to explain to a stranger)
+        - [ ] Why it needs to exist (the problem or desire driving it)
+        - [ ] Who it's for (even if just themselves)
+        - [ ] What "done" looks like (observable outcomes)
+
+        Four things. If they volunteer more, capture it.
+    </context-checklist>
+
+    <decision-gate>
+        When you could write a clear product-vision.md, offer to proceed:
+
+        - header: "Ready?"
+        - question: "I think I understand what you're after. Ready to create product-vision.md?"
+        - options:
+        - "Create product-vision.md" — Let's move forward
+        - "Keep exploring" — I want to share more / ask me more
+
+        If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+        Loop until "Create product-vision.md" selected.
+    </decision-gate>
+
+    <anti-patterns>
+        - **Checklist walking** — Going through domains regardless of what they said
+        - **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+        - **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+        - **Interrogation** — Firing questions without building on answers
+        - **Rushing** — Minimizing questions to get to "the work"
+        - **Shallow acceptance** — Taking vague answers without probing
+        - **Premature constraints** — Asking about tech stack before understanding the idea
+    </anti-patterns>
+
+</questioning-guide>

package/agile-context-engineering/utils/ui-formatting.md

@@ -0,0 +1,300 @@
+<ui_patterns>
+
+# ACE UI Formatting Guide
+
+All agent output MUST follow these patterns. Consistency is the product.
+
+---
+
+## Brand Identity
+
+- **Prefix**: `ACE` — used in all banners and headers
+- **Separator**: `>` — routes context after prefix
+- **Hierarchy**: `Epic > Feature > Story > Task`
+- **Voice**: Precise, confident, structured. No fluff. No filler.
+
+---
+
+## Banners
+
+Banners frame every major output block. They signal phase transitions.
+
+### Primary Banner (phase start/end)
+
+```
+╔══════════════════════════════════════════════════╗
+║  ACE > Plan Project                              ║
+╚══════════════════════════════════════════════════╝
+```
+
+### Section Banner (within a phase)
+
+```
+┌──────────────────────────────────────────────────┐
+│  ACE > Refine Story > E1-F2-S3                   │
+└──────────────────────────────────────────────────┘
+```
+
+### Completion Banner
+
+```
+╔══════════════════════════════════════════════════╗
+║  ACE > Story Verified                            ║
+║  E1-F2-S3 "User can reset password"              ║
+╚══════════════════════════════════════════════════╝
+```
+
+### Rules
+
+- Banner width: **exactly 52 characters** inner width
+- Left-pad content with **2 spaces** inside the border
+- Right-pad to fill the border width
+- NEVER mix border styles (`═══` for primary, `───` for section)
+- ALWAYS include the `ACE >` prefix
+
+---
+
+## Progress Indicators
+
+### Phase Progress Bar
+
+```
+  Progress  [████████████░░░░░░░░]  60%  (3/5 tasks)
+```
+
+- Bar width: **20 characters** fixed
+- `█` = completed, `░` = remaining
+- Always show percentage AND fraction
+
+### Sprint Progress Table
+
+```
+  Story       Status   Tasks    Progress
+  ─────────   ──────   ──────   ────────
+  E1-F1-S1    done     4/4      ████ 100%
+  E1-F1-S2    active   2/6      █░░░  33%
+  E1-F1-S3    queued   0/3      ░░░░   0%
+```
+
+### Story Task Tracker
+
+```
+  Tasks for E1-F2-S3:
+  ────────────────────
+  [x] Set up password reset endpoint
+  [x] Create email template
+  [ ] Add rate limiting              << active
+  [ ] Write integration tests
+  [ ] Update API documentation
+```
+
+- `[x]` = done, `[ ]` = pending
+- `<< active` marker on current task
+- Indented with **2 spaces**
+
+### Status Symbols
+
+| Symbol | Meaning       | When to use                    |
+|--------|---------------|--------------------------------|
+| `[x]`  | Done          | Task/story completed           |
+| `[ ]`  | Pending       | Task/story not started         |
+| `[~]`  | In progress   | Currently executing            |
+| `[!]`  | Blocked       | Cannot proceed, dependency     |
+| `[?]`  | Needs input   | Waiting on user decision       |
+
+---
+
+## Hierarchy Display
+
+### Backlog Tree
+
+```
+  E1  Platform Foundation
+  ├── F1  User Authentication          3 stories
+  │   ├── S1  Sign up flow             [x] done
+  │   ├── S2  Login flow               [~] active
+  │   └── S3  Password reset           [ ] queued
+  ├── F2  Dashboard                    2 stories
+  │   ├── S1  Layout scaffolding       [ ] queued
+  │   └── S2  Data widgets             [ ] queued
+  └── F3  Settings Page                0 stories
+```
+
+- Tree characters: `├──`, `└──`, `│`
+- ID left-aligned, name after **2 spaces**, metadata right-aligned
+- Leaf nodes show status symbol
+
+### Breadcrumb Navigation
+
+```
+  ACE > E1 Platform Foundation > F2 Dashboard > S1 Layout scaffolding
+```
+
+- Always show full path from Epic down
+- Separate levels with ` > `
+
+---
+
+## Content Blocks
+
+### Info Block
+
+```
+  i  Story E1-F1-S2 has 6 tasks estimated at ~4 hours total.
+     Prerequisites: E1-F1-S1 must be complete.
+```
+
+- Prefix: `i` (lowercase, 2-space indent)
+- Continuation lines aligned under text, not under prefix
+
+### Warning Block
+
+```
+  !  Story E1-F2-S3 has no acceptance criteria defined.
+     Run /ace:refine-story E1-F2-S3 before executing.
+```
+
+- Prefix: `!`
+- Include actionable next step
+
+### Success Block
+
+```
+  +  All 4 tasks completed. Story E1-F1-S1 is done.
+     Commit: a3f7c2d "feat(auth): implement sign-up flow"
+```
+
+- Prefix: `+`
+- Include commit hash when relevant
+
+### Error Block
+
+```
+  x  Task 3 failed: test suite has 2 failing assertions.
+     See output above. Fix and re-run /ace:execute-story E1-F1-S2.
+```
+
+- Prefix: `x`
+- Always include recovery instruction
+
+---
+
+## Decision Points
+
+When presenting choices to the user:
+
+```
+┌──────────────────────────────────────────────────┐
+│  ACE > Decision Required                         │
+└──────────────────────────────────────────────────┘
+
+  This feature has two possible approaches:
+
+  [A]  API-first — Build endpoints, then UI
+       Faster backend iteration, frontend blocked initially.
+
+  [B]  Vertical slice — Build one flow end-to-end
+       Slower start, but validates assumptions early.
+
+  Recommendation: [B] for new domains, [A] for well-understood ones.
+```
+
+- Options labeled `[A]`, `[B]`, `[C]` — never more than 4
+- Each option: label + short name + description on next line
+- Recommendation line at the end if applicable
+
+---
+
+## Transitions & Flow
+
+### Next Action Block
+
+Every phase completion MUST end with a "Next" block:
+
+```
+  Next > /ace:plan-feature E1-F1
+         Break this epic into features and stories.
+```
+
+- Format: `Next >` followed by the command
+- Second line: brief description of what it does
+- This is MANDATORY after every completion
+
+### Phase Transition
+
+```
+╔══════════════════════════════════════════════════╗
+║  ACE > Story Refined                             ║
+║  E1-F1-S2 ready for execution                    ║
+╚══════════════════════════════════════════════════╝
+
+  Summary:
+  ────────
+  6 tasks defined, all acceptance criteria mapped.
+  Estimated effort: ~4 hours.
+
+  Next > /ace:execute-story E1-F1-S2
+         Execute this story with atomic commits.
+```
+
+---
+
+## Commit Messages
+
+ACE enforces conventional commits tied to the hierarchy:
+
+```
+  feat(auth): implement email verification flow
+
+  Story: E1-F1-S2
+  Task: 3/6 — Add verification endpoint
+```
+
+- First line: conventional commit format
+- Blank line, then `Story:` and `Task:` metadata
+- Keep first line under 72 characters
+
+---
+
+## Spacing & Indentation Rules
+
+| Element              | Indentation  |
+|----------------------|-------------|
+| Banner content       | 2 spaces    |
+| Body text            | 2 spaces    |
+| Nested list items    | 4 spaces    |
+| Code/command blocks  | 4 spaces    |
+| Table content        | 2 spaces    |
+| Continuation lines   | Align under text start |
+
+- **One blank line** between sections
+- **Two blank lines** before a new banner
+- **No trailing whitespace**
+- **No more than 3 consecutive blank lines** anywhere
+
+---
+
+## Typography
+
+- IDs are **always monospace-styled**: `E1`, `F2`, `S3`
+- Commands are **always code-formatted**: `/ace:plan-story`
+- File paths are **always code-formatted**: `.ace/backlog/E1/F1-auth.md`
+- Emphasis for key terms: **bold** only, never *italic* in output
+- Numbers: use digits, not words (`3 stories`, not `three stories`)
+
+---
+
+## Anti-Patterns
+
+- Varying banner widths or border styles within a session
+- Missing `ACE >` prefix in banners
+- Random emoji in output — ACE uses **zero emoji** in structured output
+- Skipping the `Next >` block after a phase completion
+- Using prose paragraphs where a table or list would be clearer
+- Inconsistent ID formatting (`e1-f1` vs `E1-F1` — always uppercase)
+- Status text without a symbol (`done` alone — use `[x] done`)
+- Banners for trivial messages — only use banners for phase boundaries
+- Mixing `ACE >` with other prefix styles
+- Omitting the hierarchy breadcrumb when context is ambiguous
+
+</ui_patterns>