@kienha/anti-chaotic 1.0.2 → 1.0.6

package/.agent/workflows/documentation.md

@@ -0,0 +1,123 @@
+---
+description: Generate comprehensive documentation (Architecture, API, Specs) from either Codebase or Requirements.
+---
+
+# Documentation Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Apply `.agent/rules/documents.md` for all document creation.
+
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                    |
+| :------------------------------------------- | :--------------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Analyze complex architecture, design decisions |
+| `mcp_context7_query-docs`                    | Research framework patterns, diagram syntax    |
+
+---
+
+## Step 0: Determine Mode
+
+**Determine the source of truth:**
+
+1. **From Codebase**: Reverse engineer docs from existing code.
+2. **From Requirements**: Forward engineer detailed specs (SDD, Stories) from PRD/Roadmap.
+
+---
+
+# MODE A: From Codebase
+
+## Step A1: Codebase Discovery
+
+// turbo
+
+> 💡 **MCP**: Use `sequential-thinking` to analyze unfamiliar project structures
+
+1. **Invoke `[lead-architect]` skill** to analyze codebase structure
+2. Identify: tech stack, entry points, API routes, DB schemas
+3. **WAIT** for user to confirm understanding
+
+---
+
+## Step A2: Legacy Docs Generation (Architecture, API, Schema)
+
+// turbo
+
+1. **Invoke `[lead-architect]` skill** to create:
+   - System Context (C4 Context Diagram)
+   - Component View (C4 Component Diagram)
+2. **Invoke `[backend-developer]` skill** to:
+   - Document API endpoints
+   - Generate Entity Relationship Diagram (ERD)
+3. Save to `docs/030-Specs/` and `docs/030-Specs/Architecture/`
+
+---
+
+# MODE B: From Requirements
+
+**Prerequisite**: Existing PRD (from `/brainstorm`).
+
+## Step B1: Create SDD (System Design Document)
+
+// turbo
+
+> 💡 **MCP**:
+>
+> - **MUST** use `sequential-thinking` for architectural decisions
+> - Use `context7` with `/vercel/next.js`, `/supabase/supabase` for tech stack research
+
+1. **Invoke `[lead-architect]` skill** to draft:
+   - High-level system architecture
+   - Technology stack decisions
+   - Component diagram
+   - Data flow overview
+2. Create `draft-sdd.md` artifact
+3. After approval → Save to `docs/030-Specs/Architecture/SDD-{ProjectName}.md`
+
+---
+
+## Step B2: Create Epics & Use Cases
+
+// turbo
+
+1. **Invoke `[business-analysis]` skill** to:
+   - Break PRD features into Epics (`docs/022-User-Stories/Epics/`)
+   - Define Use Cases with Mermaid diagrams (`docs/020-Requirements/Use-Cases/`)
+2. Create artifacts for review before saving
+
+---
+
+## Step B3: Create User Stories
+
+// turbo
+
+1. **Invoke `[business-analysis]` skill** to create:
+   - User Stories with Acceptance Criteria (`docs/022-User-Stories/Backlog/`)
+   - Complexity estimates
+2. Create `draft-user-stories.md` artifact
+3. After approval → Save
+
+---
+
+## Step B4: Create ADRs (Optional)
+
+// turbo
+
+**Skip if**: User did not request ADRs.
+
+1. **Invoke `[lead-architect]` skill** to document technical decisions.
+2. Save to `docs/030-Specs/Architecture/ADR-{NNN}-{Decision}.md`
+
+---
+
+# Finalize
+
+## Step X: Finalize
+
+// turbo
+
+1. Create/update MOC files
+2. Validate wiki-links and frontmatter
+3. Present summary and suggest next steps (`/ui-ux-design` or `/implement-feature`)

package/.agent/workflows/implement-feature.md

@@ -0,0 +1,146 @@
+---
+description: Orchestrates feature implementation from specification to deployment.
+---
+
+# Feature Implementation Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Read `.agent/rules/documents.md` before creating any document.
+
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                       | Example Query                  |
+| -------------------------------------------- | ------------------------------------------------- | ------------------------------ |
+| `mcp_sequential-thinking_sequentialthinking` | Complex decisions, debugging, architecture design | Break down feature into tasks  |
+| `mcp_context7_resolve-library-id`            | Find library ID before querying docs              | "react hook form"              |
+| `mcp_context7_query-docs`                    | Research library patterns, APIs, best practices   | "How to setup auth in Next.js" |
+
+---
+
+## Step 0: Quick Specification (Optional)
+
+**Skip if**: User Stories or specs already exist in `docs/`.
+
+> 💡 **MCP**: Use `sequential-thinking` to analyze ambiguous requirements
+
+1. **Invoke `[product-manager]` skill** to clarify requirements
+2. Create `feature-spec.md` artifact with: Goal, User, Acceptance Criteria
+3. **WAIT** for user confirmation
+
+---
+
+## Step 1: Locate Existing Artifacts
+
+// turbo
+
+> 💡 **MCP**: Use `context7` to research unfamiliar tech in existing codebase
+
+1. Search `docs/` for related: User Stories, SDD, Designs
+2. **Invoke `[lead-architect]` skill** to identify scope and dependencies
+3. List files to create/modify
+4. **WAIT** for user to confirm scope
+
+---
+
+## Step 2: Implementation Plan
+
+// turbo
+
+> 💡 **MCP**: **MUST** use `sequential-thinking` to break down complex features into atomic tasks
+
+1. **Invoke `[lead-architect]` skill** to create task breakdown
+2. Create `implementation-plan.md` artifact with phased tasks
+3. Save to `docs/050-Tasks/Task-{FeatureName}.md` after approval
+4. **WAIT** for user approval
+
+---
+
+## Step 3: Design Review (If UI Feature)
+
+// turbo
+
+**Skip if**: Feature is purely backend/API.
+
+> 💡 **MCP**: Use `context7` with `/radix-ui/*` or `/shadcn/*` for component patterns
+
+1. Check `docs/040-Design/` for existing designs
+2. **Invoke `[designer]` skill** for new component specifications
+3. **WAIT** for user confirmation
+
+---
+
+## Step 4: Backend Implementation
+
+// turbo
+
+> 💡 **MCP**:
+>
+> - Use `context7` with `/supabase/supabase`, `/prisma/prisma` for DB patterns
+> - Use `sequential-thinking` for complex business logic
+
+1. **Invoke `[backend-developer]` skill** for:
+   - Data models/migrations
+   - API endpoints/server functions
+   - Unit tests (TDD approach)
+2. Run tests and verify
+3. **WAIT** for user checkpoint
+
+---
+
+## Step 5: Frontend Implementation
+
+// turbo
+
+> 💡 **MCP**: Use `context7` with `/vercel/next.js`, `/tanstack/react-query`, `/react-hook-form/*` for patterns
+
+1. **Invoke `[frontend-developer]` skill** for:
+   - Components following design specs
+   - State management
+   - Component tests
+2. **WAIT** for user checkpoint
+
+---
+
+## Step 6: Integration & QA
+
+// turbo
+
+> 💡 **MCP**:
+>
+> - Use `context7` with `/vitest-dev/vitest`, `/playwright/*` for testing patterns
+> - Use `sequential-thinking` to analyze test failures
+
+1. **Invoke `[qa-tester]` skill** for:
+   - E2E test execution
+   - Acceptance criteria verification
+   - Edge case testing
+2. Create `qa-report.md` artifact
+3. **WAIT** for user to confirm ready
+
+---
+
+## Step 7: Finalize
+
+// turbo
+
+1. **Invoke `[lead-architect]` skill** to:
+   - Update MOC files
+   - Move task to `docs/050-Tasks/Completed/`
+   - Update API/changelog if applicable
+2. Present completion summary with next steps
+
+---
+
+## Quick Reference
+
+| Step | Skill              | Output                 |
+| ---- | ------------------ | ---------------------- |
+| 0    | product-manager    | feature-spec.md        |
+| 1-2  | lead-architect     | implementation-plan.md |
+| 3    | designer           | Component specs        |
+| 4    | backend-developer  | API, Models, Tests     |
+| 5    | frontend-developer | Components, Tests      |
+| 6    | qa-tester          | qa-report.md           |
+| 7    | lead-architect     | Updated docs           |

package/.agent/workflows/ui-ux-design.md

@@ -1,77 +1,96 @@
 ---
-description: Transform a requirements document into a comprehensive UI/UX design.
+description: Transform requirements into comprehensive UI/UX design deliverables.
 ---
 
 # UI/UX Design Workflow
 
-This workflow guides the process of creating a UI/UX design from a requirements document.
+> [!IMPORTANT]
+> **MANDATORY**: Apply `.agent/rules/documents.md` for all documentation structure.
 
-## Step 1: Analyze Requirements
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                  | When to Use                                     |
+| ------------------------- | ----------------------------------------------- |
+| `mcp_context7_query-docs` | Research UI libraries (shadcn, radix, tailwind) |
+| `generate_image`          | Create low-fi wireframes or conceptual assets   |
+
+---
 
-**Goal**: Extract core design drivers from the input document.
+## Step 0: Discovery & Context
 
-1.  **Read the Document**: Use `read_file` or `view_file` to inspect the target requirements document.
-2.  **Identify Key Elements**:
-    - **Target Audience**: Who is this for?
-    - **Problem Statement**: What are we solving?
-    - **Core Features**: What functionality is required?
-    - **Constraints**: Technical, brand, or platform limitations?
-3.  **Synthesize**: Create a brief summary of the design goals.
+// turbo
 
-## Step 2: Define Design System
+1. **Invoke `[designer]` skill** to:
+   - Check if Design System exists in `docs/`
+   - Analyze requirements/PRD
+   - Determine design scope (New System vs New Feature)
+2. **WAIT** for analysis result
 
-**Goal**: Establish the visual language. **Prioritize the specific design requirements found in the document.**
+---
 
-1.  **Check Existing Codebase**:
-    - Scan for existing styles (`app.css`, `tailwind.config.ts`, `globals.css`) or UI components.
-    - **Condition**:
-      - **IF Codebase has Design System**: Analyze and extract the current design system (tokens, colors, typography). Use this as the foundation. Then, apply specific user requirements or overrides from the document on top of this existing system.
-      - **IF New/Empty Codebase**: Create the design system from scratch based strictly on the requirements document.
+## Step 1: Design System (If Needed)
 
-2.  **Consult Designer Skill**: Use `designer` skill for principles to ensure high quality (Premium, Distinctive), but ensure strict adherence to the document's specific constraints.
+// turbo
 
-3.  **Determine Aesthetic** (derived from Doc or Codebase):
-    - **Visual Style**: Minimal/Clean vs. Bold/Playful (as defined in Doc).
-    - **Theme**: Light vs. Dark mode preference.
+**Skip if**: Design system already exists.
 
-4.  **Select Foundations**:
-    - **Typography**: Adhere to existing fonts if present; otherwise select based on Doc (e.g., Inter, Roboto, Outfit).
-    - **Color Palette**: Extract from codebase or define new primary/secondary/neutral colors based on Doc.
-    - **Spacing/Layout**: Harmonize with existing grid or define a new one (e.g., 4px/8px grid).
+> 💡 **MCP**: Use `context7` with `/tailwindcss/tailwindcss` or `/shadcn/ui` for config
 
-## Step 3: Map User Flows
+1. **Invoke `[designer]` skill** to define:
+   - Typography, Colors, Spacing scale
+   - Component primitives (Buttons, Inputs, Cards)
+   - Motion principles
+2. Create/Update Design System documentation
+3. **WAIT** for user approval
 
-**Goal**: Outline how users interact with the system.
+---
 
-1.  **Identify Critical Paths**: What are the main tasks (e.g., "Sign Up", "Checkout", "Create Post")?
-2.  **Step-by-Step Flow**: List the screens or states users will encounter for each path.
-3.  **Information Architecture**: Structure the navigation and hierarchy suitable for the flows.
+## Step 2: Component & Flow Design
 
-## Step 4: Create Rapid Prototypes
+// turbo
 
-**Goal**: Create high-fidelity HTML/CSS prototypes for user approval. **Focus on "Look & Feel" and "Flow" rather than production component code.**
+1. **Invoke `[designer]` skill** to:
+   - Map user flows based on User Stories
+   - Define necessary components (Reuse vs New)
+   - Create component specifications
+2. Create flow and component documentation
+3. **WAIT** for user review
 
-1.  **Orchestrate Project Structure**:
-    - All design artifacts must be contained within a `prototype/` directory at the project root.
-    - Sub-assets (images, icons, illustrations) must be stored in `prototype/assets/`.
+---
 
-2.  **Generate Assets First**:
-    - **Proactively use "Nano Banana" (`generate_image`)** to create high-fidelity demo images, icons, or UI backgrounds.
-    - **Asset Storage**: Save these generated images directly into `prototype/assets/`.
+## Step 3: Prototyping
 
-3.  **Build Interactive Prototypes**:
-    - Create functional **HTML/CSS files** (e.g., `prototype/home.html`, `prototype/dashboard.html`).
-    - **Focus**: Visual impact, layout, spacing, and responsiveness.
-    - **Do NOT**: Break down into complex React/Vue components (e.g., `.tsx`, `.vue`) at this stage. Keep it as raw HTML/CSS for easy iteration.
-    - **Resource Linking**: Ensure all image `src` paths correctly reference the `./assets/` folder relative to the prototype file.
+// turbo
 
-4.  **Review against Principles**: Check against the designer skill's "Core Design Principles" (Intentionality, Distinction, Technical Excellence).
+> 💡 **MCP**: Use `generate_image` for visual concept validation if needed
 
-## Step 5: Verification & Approval
+1. **Invoke `[frontend-developer]` skill** to:
+   - Build HTML/CSS prototypes in `prototype/` (keep it simple)
+   - Or create interactive mockups
+2. **Invoke `[designer]` skill** to:
+   - Review for accessibility (Contrast, Semantic HTML)
+   - Check alignment with Design System
+
+---
+
+## Step 4: Review & Handoff
+
+// turbo
+
+1. Present prototypes to user
+2. Collect and apply feedback
+3. Update MOC files and finalize docs
+4. **Handoff**: Trigger `/implement-feature` if approved
+
+---
 
-**Goal**: Get user buy-in on the design directives.
+## Quick Reference
 
-1.  **Present Prototypes**: Show the `prototype/*.html` files to the user for review.
-2.  **Iterate**: Refine the HTML/CSS based on feedback.
-3.  **Approval Gate**: Explicitly ask: _"Does this prototype meet your expectations?"_
-4.  **Handoff Prep**: **ONLY after approval**, verify technical feasibility and prepare for the developer to convert into production components.
+| Step | Skill              | Output              |
+| ---- | ------------------ | ------------------- |
+| 0    | designer           | Scope analysis      |
+| 1    | designer           | Design System docs  |
+| 2    | designer           | Flow/Component docs |
+| 3    | frontend-developer | HTML Prototypes     |