agentic-sdlc 1.5.1 → 1.8.1

package/.agent/knowledge-base/architecture/README.md

@@ -1,98 +0,0 @@
-# Architecture Knowledge Base
-
-This directory contains knowledge base entries related to architecture decisions, database technologies, system design patterns, and technical infrastructure.
-
-## Current Entries
-
-### KB-2026-01-01-003: Neo4j Graph Database Skills
-**Category:** Architecture / Database Technology  
-**Date:** 2026-01-01  
-**Prepared By:** @SA
-
-Comprehensive guide to Neo4j graph database covering:
-- **Cypher Query Language:** Complete syntax reference and patterns
-- **Performance Optimization:** Indexing strategies and query tuning
-- **Data Modeling:** Best practices for graph design
-- **Advanced Techniques:** Full-text search, spatial indexing, graph algorithms
-- **Integration:** Driver examples for Python, JavaScript, Java
-- **Deployment:** Configuration, backup, security best practices
-
-**Key Skills Covered:**
-- Creating and querying nodes and relationships
-- Cypher pattern matching and path finding
-- Index creation and optimization strategies
-- Performance profiling with EXPLAIN and PROFILE
-- Full-text and spatial indexing
-- Graph algorithms (shortest path, PageRank, community detection)
-- Data modeling patterns for common use cases
-- Security and access control
-- Backup and recovery procedures
-
-**Use Cases:**
-- Social network analysis
-- Fraud detection systems
-- Knowledge graphs
-- Recommendation engines
-- Network and IT operations
-- Access control systems
-
-**Quick Reference:**
-- Essential Cypher commands cheat sheet
-- Performance optimization checklist
-- Common graph patterns
-- Integration code examples
-- Deployment configurations
-
----
-
-## Architecture Decision Records
-
-This section tracks major architectural decisions made in the project:
-
-| Decision | Technology | Rationale | Date | KB Entry |
-|----------|-----------|-----------|------|----------|
-| Graph Database | Neo4j | Optimal for highly connected data, relationship-first queries | 2026-01-01 | KB-2026-01-01-003 |
-
----
-
-## How to Use This Knowledge
-
-### For System Analysts (@SA)
-1. **Before Design:** Review relevant architecture patterns
-2. **During Design:** Reference best practices and anti-patterns
-3. **After Implementation:** Document decisions and learnings
-
-### For Developers (@DEV)
-1. **Before Coding:** Check for existing patterns and solutions
-2. **During Development:** Follow documented best practices
-3. **After Completion:** Update KB with new insights
-
-### For DevOps (@DEVOPS)
-1. **Deployment Planning:** Review configuration and scaling strategies
-2. **Operations:** Reference backup, monitoring, and security procedures
-3. **Troubleshooting:** Check performance optimization guides
-
----
-
-## Related Categories
-
-- **Features:** Implementation patterns and UI/UX considerations
-- **Performance:** Optimization techniques and benchmarks
-- **Security:** Security best practices and vulnerability mitigations
-- **Bugs:** Common issues and their resolutions
-
----
-
-## Contributing
-
-When adding new architecture entries:
-1. Use the knowledge entry template
-2. Include decision rationale
-3. Document alternatives considered
-4. Provide code examples
-5. Link to related entries
-6. Update this README
-
----
-
-#architecture #knowledge-base #system-design #database

package/.agent/knowledge-base/bugs/.gitkeep

@@ -1 +0,0 @@
-# This folder stores bug patterns and solutions

package/.agent/knowledge-base/bugs/KB-2026-01-02-yaml-special-character-escaping.md

@@ -1,56 +0,0 @@
----
-title: "YAML Frontmatter Special Character Escaping"
-category: bug
-priority: medium
-sprint: sprint-[N]
-date: 2026-01-02
-tags: [yaml, parsing, frontmatter, knowledge-base, escaping]
-related_files: [tools/utils/kb_manager.py]
-attempts: 1
-time_saved: "20 minutes (future reuse)"
-author: "DEV"
----
-
-## Problem
-YAML parser fails when frontmatter contains unquoted special characters like `@`:
-
-```
-found character '@' that cannot start any token
-  author: @DEV + @UIUX
-          ^
-```
-
-## Root Cause
-In YAML, `@` is a reserved indicator that cannot appear unquoted at the start of a value. The YAML 1.1 spec reserves `@` for future use.
-
-## Solution
-Quote values containing special characters:
-
-```yaml
-# ❌ Invalid
-author: @DEV + @UIUX
-
-# ✅ Valid
-author: "DEV + UIUX"
-```
-
-## Prevention
-1. Always quote values containing: `@`, `:`, `#`, `*`, `!`, `|`, `>`
-2. Use KB entry templates that pre-quote author fields
-3. Add YAML validation to `/compound` workflow
-4. Document YAML escaping rules in KB README
-
-## Validation Script
-```python
-import yaml
-try:
-    yaml.safe_load(frontmatter)
-except yaml.YAMLError as e:
-    print(f"Invalid YAML: {e}")
-```
-
-## Related Patterns
-- KB entry creation workflow
-- YAML best practices
-
-#bug #yaml #knowledge-base #escaping

package/.agent/knowledge-base/bugs/medium/KB-2026-01-01-001-example-auto-learned.md

@@ -1,198 +0,0 @@
-# Knowledge Entry - React Hydration Mismatch in Astro Components
-
-## Document Info
-| Field | Value |
-|-------|-------|
-| ID | KB-2026-01-01-001 |
-| Date | 2026-01-01 |
-| Author | @DEV |
-| Category | Bug Pattern |
-| Severity | Medium |
-| Auto-Generated | Yes |
-| Source Task | TASK-123 |
-| Sprint | 1 |
-| Project | Landing Page |
-| Tags | #react, #astro, #hydration, #ssr, #auto-learned |
-
----
-
-## Problem / Challenge
-
-### Description
-React components in Astro were throwing hydration mismatch errors when using client-side state management. The error appeared only in production builds, not during development.
-
-### Context
-- **Platform:** Web
-- **Technology:** Astro 4.16, React 18, Tailwind CSS
-- **Environment:** Production
-- **Affected Components:** Features.astro, Hero.astro
-
-### Symptoms
-- Console error: "Hydration failed because the initial UI does not match what was rendered on the server"
-- Visual flash of unstyled content (FOUC)
-- Interactive elements not responding immediately
-
-### Impact
-- **Users Affected:** 100% of visitors
-- **Business Impact:** Poor first impression, potential bounce rate increase
-- **Technical Impact:** Client-side JavaScript re-rendering entire component
-
----
-
-## Root Cause Analysis
-
-### What Happened
-Astro was server-rendering React components with initial state, but client-side hydration was using different initial values, causing a mismatch.
-
-### Why It Happened
-The component was using `Date.now()` for generating unique IDs during SSR, which produced different values during client-side hydration.
-
-### Contributing Factors
-- Server and client running at different times
-- No stable ID generation strategy
-- Missing `client:load` directive specification
-
-### Code/Configuration Example
-```jsx
-// Problematic code
-export default function Features() {
-  const [id] = useState(() => `feature-${Date.now()}`);
-  return <div id={id}>...</div>;
-}
-```
-
----
-
-## Solution
-
-### Approach
-Use stable, deterministic IDs that are consistent between server and client rendering.
-
-### Implementation
-```jsx
-// Fixed code
-export default function Features() {
-  const [id] = useState('feature-static-id');
-  // OR use useId hook in React 18+
-  const id = useId();
-  return <div id={id}>...</div>;
-}
-```
-
-### Configuration Changes
-```astro
----
-// In Astro component, specify hydration strategy
-import Features from '../components/Features';
----
-
-<Features client:load />
-```
-
-### Steps to Resolve
-1. Identify components with dynamic ID generation
-2. Replace `Date.now()` or `Math.random()` with stable IDs
-3. Use React 18's `useId()` hook for unique IDs
-4. Add explicit `client:load` directive in Astro
-5. Test in production build mode
-
-### Time to Resolve
-- **First Attempt:** 2 hours (tried various hydration strategies)
-- **Total Attempts:** 3
-- **Final Resolution:** 4 hours
-
----
-
-## Prevention
-
-### How to Avoid in Future
-- Always use stable IDs for SSR components
-- Use React 18's `useId()` hook for unique identifiers
-- Test production builds before deployment
-- Avoid time-based or random values in initial render
-
-### Detection Strategy
-- Run `npm run build && npm run preview` before deployment
-- Check browser console for hydration warnings
-- Add automated tests for SSR/hydration consistency
-
-### Code Review Checklist
-- [ ] No `Date.now()` or `Math.random()` in component initialization
-- [ ] Using `useId()` for dynamic IDs
-- [ ] Explicit hydration directive specified
-- [ ] Tested in production build mode
-
----
-
-## Related Issues
-
-### Similar Bugs/Features
-- Hydration issues with conditional rendering
-- SSR state management problems
-
-### Related Documentation
-- [React 18 Hydration](https://react.dev/reference/react-dom/client/hydrateRoot)
-- [Astro Client Directives](https://docs.astro.build/en/reference/directives-reference/#client-directives)
-
-### Related Knowledge Entries
-- KB-2026-01-01-002: Astro Island Architecture Best Practices
-
----
-
-## Lessons Learned
-
-### What Worked Well
-- React 18's `useId()` hook solved the problem elegantly
-- Production build testing caught the issue before deployment
-- Astro's explicit hydration directives provide good control
-
-### What Didn't Work
-- Trying to synchronize timestamps between server and client
-- Using localStorage to persist IDs (not available during SSR)
-
-### Key Takeaways
-1. Always test SSR applications in production mode
-2. Avoid non-deterministic values in initial render
-3. Use framework-provided solutions (useId) over custom implementations
-4. Explicit is better than implicit for hydration strategies
-
----
-
-## Search Keywords
-hydration, mismatch, astro, react, ssr, server-side-rendering, useId, Date.now, production-build, FOUC
-
----
-
-## Verification
-
-### How to Test
-```bash
-# Build and preview production
-npm run build
-npm run preview
-
-# Check browser console for errors
-# Look for "Hydration failed" messages
-```
-
-### Expected Result
-- No hydration warnings in console
-- Smooth rendering without FOUC
-- Interactive elements work immediately
-
-### Regression Test
-- [x] Test case added to prevent recurrence
-- [x] Automated test created for SSR consistency
-
----
-
-## References
-- Bug Report: TASK-123
-- Pull Request: PR-456
-- Documentation: https://docs.astro.build/en/guides/framework-components/
-- External Resources: https://react.dev/reference/react/useId
-
----
-
-#knowledge-base #bug-pattern #react #astro #hydration #ssr #auto-learned #sprint-1
-

package/.agent/knowledge-base/features/.gitkeep

@@ -1 +0,0 @@
-# This folder stores complex feature implementations