@kienha/anti-chaotic 1.0.2 → 1.0.6

package/.agent/skills/rules-workflows/references/rules-guide.md

@@ -1,101 +1,118 @@
-# Rules Creation Guide
+# High-Performance Rule Governance
 
-## Overview
+> "Rules are the automated guardrails that ensure consistency without micromanagement."
 
-Workspace rules live in the `.agent/rules` folder of your workspace or git root. Rules are persistent instructions that guide _how_ the Agent thinks and acts.
+This guide establishes the framework for defining, enforcing, and managing Agent behavior standards across the organization.
 
-## Creating Rules via UI
+## 1. The Core Philosophy
 
-1. Open **Customizations** panel via "..." dropdown in agent panel
-2. Navigate to **Rules** panel
-3. Select **+ Global** (cross-workspace) or **+ Workspace** (project-specific)
+In a high-functioning AI-driven organization, Rules serve two critical functions:
 
----
+1.  **Context Injection**: Instantly downloading "Senior Engineer" context into the Agent's specific session.
+2.  **Operational Guardrails**: Preventing known anti-patterns (e.g., "Never commit secrets", "Always use strict TS").
 
-## Rule Activation Types
+| Level                 | Purpose                                | Example                    |
+| :-------------------- | :------------------------------------- | :------------------------- |
+| **L1: Critical**      | Security & Compliance (Non-negotiable) | `security-policy.md`       |
+| **L2: Architectural** | Tech Stack Standards                   | `nextjs-best-practices.md` |
+| **L3: Stylistic**     | Team preferences                       | `naming-conventions.md`    |
 
-At the rule level, you can define **how** a rule should be activated:
+## 2. Activation Strategy (Context Management)
 
-| Type               | Description                                                                                                                     |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| **Manual**         | The rule is manually activated via `@mention` in Agent's input box                                                              |
-| **Always On**      | The rule is always applied to every interaction                                                                                 |
-| **Model Decision** | Based on a natural language description of the rule, the model decides whether to apply the rule                                |
-| **Glob**           | Based on the glob pattern you define (e.g., `.js`, `src/**/*.ts`), the rule will be applied to all files that match the pattern |
+The key to a responsive Agent is _Selective Activation_. Loading 100 rules confuses the context. Use activation types strategically.
 
-### When to Use Each Type
+### A. The "Always On" (Global Constitution)
 
-- **Manual**: For intensive operations like deep code reviews, refactoring strategies, or specialized analysis that shouldn't run automatically
-- **Always On**: For critical project constraints, coding standards, and domain knowledge that must be enforced on every interaction
-- **Model Decision**: For context-aware rules that should only apply when relevant (e.g., security guidelines only when working with auth)
-- **Glob**: For file-type-specific standards (e.g., React component standards for `.tsx` files)
+**Use sparingly.** Only for rules that apply to _every_ single keystroke.
 
----
+- **Triggers**: `always_on`
+- **Use Case**: Safety checks, Tone of Voice, Core Documentation links.
+- **Cost**: Consumes context window on every turn.
 
-## Rule File Templates
+### B. The "Just-in-Time" (Context-Aware)
 
-### Always-On Rule
+**The Gold Standard.** Rules that activate only when relevant.
 
-```markdown
----
-trigger: always_on
----
+- **Triggers**: `model_decision` (based on description) or `glob` (based on files).
+- **Use Case**:
+  - If user asks about "Auth" -> Load `auth-guidelines.md`.
+  - If editing `.tsx` files -> Load `react-component-standards.md`.
 
-# [Rule Name]
+### C. The "Surgical" (Manual Override)
 
-[Instructions that always apply to this workspace/globally]
-```
+**For heavy-duty tasks.**
 
-### Model-Decision Rule
+- **Triggers**: `manual`
+- **Use Case**: "Refactor this legacy code." -> User explicitly calls `@refactoring-rules`.
 
-```markdown
----
-trigger: model_decision
-description: Apply when working with authentication or security features
----
+## 3. Designing Effective Rules
 
-# Security Guidelines
+A rule is a **Directive**, not a suggestion.
 
-[Security-related instructions for the agent]
-```
+### ❌ Weak Rule
 
-### Glob-Pattern Rule
+> "Try to write good variable names and maybe use TypeScript if you can."
 
-```markdown
----
-trigger: glob
-glob: src/**/*.tsx
----
+### ✅ Strong Rule
 
-# React Component Standards
+> **Constraint**: All variables MUST follow `camelCase`.
+> **Requirement**: TypeScript `strict` mode is MANDATORY. `any` type is strictly FORBIDDEN.
 
-[Standards to apply when editing React components]
-```
+## 4. Governance & Lifecycle
 
-### Manual Rule
+Avoid "Rule Bloat" (Bureaucracy).
+
+1.  **Consolidate**: Don't have `button-rules.md` and `input-rules.md`. Have `ui-components.md`.
+2.  **Review**: If the Agent frequently ignores a rule, it is likely too vague or conflicting. Clarify or Delete it.
+3.  **Hierarchy**: Workspace Rules override Global Rules. Specific Rules override General Rules.
+
+## 5. Standard Rule Template
+
+Use this structure to create enforceable, high-clarity rules.
 
 ```markdown
 ---
-trigger: manual
+description:
+  [When should this apply? e.g., "Applied when editing Database Schema"]
+globs: ["prisma/schema.prisma"]
 ---
 
-# [Rule Name]
+# [Rule Name, e.g., Database Schema Standards]
 
-[Instructions activated via @mention]
-```
+## 1. Executive Summary
+
+All database changes must preserve backward compatibility and follow 3NF normalization.
+
+## 2. Critical Constraints (The "Musts")
+
+- 🔴 **NEVER** delete columns in a migration. Mark as `@deprecated` instead.
+- 🔴 **NEVER** use `autoincrement()` for publicly exposed IDs. Use `uuid()`.
 
-## Best Practices
+## 3. Code Patterns (The "How")
+
+### Naming
+
+- Tables: `snake_case` (plural), e.g., `users`, `order_items`.
+- Foreign Keys: `noun_id`, e.g., `user_id`.
+
+### Example
+
+✅ **Good**:
+model User {
+id String @id @default(uuid())
+}
+
+❌ **Bad**:
+model User {
+id Int @id @default(autoincrement())
+}
+```
 
-1. **Keep rules focused** - One concern per rule file
-2. **Use descriptive names** - Rule filename becomes its identifier
-3. **Leverage glob patterns** - Auto-apply rules to relevant files
-4. **Reference external files** - Use `@filename` to include context
-5. **Stay under 12,000 chars** - Split into multiple files if needed
+## 6. Advanced Context Injection
 
-## @ Mentions Syntax
+You can "hydrate" rules with dynamic context using `@` references.
 
-Reference files in rules:
+- **`@/docs/api-spec.md`**: "Enforce the API contract defined in this file."
+- **`@../shared/types.ts`**: "Use these exact types."
 
-- `@schema.prisma` - Relative to rules file
-- `@/docs/api.md` - Absolute from workspace root
-- `@../shared/types.ts` - Relative path traversal
+This allows the rule to remain static (the _policy_) while referencing dynamic content (the _data_).

package/.agent/skills/rules-workflows/references/workflows-guide.md

@@ -1,54 +1,123 @@
-# Workflows Creation Guide
+# Building High-Performance Workflows
 
-## Creating Workflows via UI
+> "Workflows are the operating system of your delivery pipeline."
 
-1. Open **Customizations** panel via "..." dropdown in agent panel
-2. Navigate to **Workflows** panel
-3. Click **+ Global** or **+ Workspace** to create workflow
+This guide is designed for Project Managers, COOs, and Architects to codify operational excellence into executable Agent processes.
 
-## Workflow File Template
+## 1. The Core Philosophy
+
+Effective workflows shift the Agent from "Ad-hoc Assistant" to "Autonomous Operator".
+
+| Ad-hoc Request          | Systematized Workflow                                             |
+| :---------------------- | :---------------------------------------------------------------- |
+| "Help me test this."    | **Run `/qa-feature`**: Analyze -> Test Plan -> Execute -> Report. |
+| "Deploy this."          | **Run `/deploy`**: Lint -> Build -> Test -> Staging -> Prod.      |
+| **High Cognitive Load** | **Zero Cognitive Load**                                           |
+
+## 2. Anatomy of an Effective Workflow
+
+A workflow is not just a list of steps. It is a **Contract of Execution**.
+
+### Key Components
+
+1.  **The Trigger**: Explicit starting condition (User request, file change, manual invocation).
+2.  **The Context**: Loading necessary rules (`rules/documents.md`) and skills (`[product-manager]`).
+3.  **The Process**: Sequential steps with explicit hand-offs.
+4.  **The Verification**: Mandatory checkpoints to prevent error propagation.
+
+## 3. Designing for Efficiency (The "COO Mindset")
+
+To build workflows that work at scale, apply these principles:
+
+### A. Principle of Delegation (Process vs. Skill)
+
+**Never hardcode specific technical knowledge in a workflow.**
+
+- ❌ **Fragile**: "Step 1: Run `npm install react@18`."
+- ✅ **Robust**: "Step 1: Install dependencies using standard practices defined in `[frontend-developer]` skill."
+
+### B. Principle of "Turbo" execution
+
+**Optimize for speed where safety allows.**
+Use the `// turbo` annotation for steps that are read-only or safe to retry. This allows the Agent to execute without stopping for approval.
+
+- **Use for**: Reading files, generating docs, running local tests.
+- **Avoid for**: Deleting files, pushing to production, external API calls with costs.
+
+### C. Principle of "Stop-the-Line" (Checkpoints)
+
+**Fail early, fail loudly.**
+Insert `**WAIT**` steps after critical actions (e.g., after Requirement Analysis, before Deployment). This is your quality gate.
+
+## 4. Structural Template
+
+Use this structure for all production-grade workflows:
 
 ```markdown
 ---
-description: [Brief description for workflow discovery]
+description:
+  [Action-oriented description, e.g., "End-to-end Feature Implementation"]
 ---
 
-# Workflow Title
+# [Workflow Name]
+
+## 1. Initialization
+
+1. Load Global Rules: `documents.md`.
+2. Analyze Context: Identify touched files.
 
-[Optional overview of what this workflow accomplishes]
+## 2. Phase I: Definition (The "PM" Phase)
 
-## Step 1: [Action Name]
+> 💡 **Tip**: Clarify before coding.
 
-[Detailed instructions for this step]
+1. Invoke **[product-manager]** to refine requirements.
+   // turbo
+2. Create `docs/specs/feature-x.md`.
+3. **WAIT** for user approval.
 
-## Step 2: [Action Name]
+## 3. Phase II: Execution (The "Dev" Phase)
 
-[Detailed instructions for this step]
+1. Read `docs/specs/feature-x.md`.
+2. Invoke **[lead-architect]** to update `implementation-plan.md`.
+3. Invoke **[backend-developer]** for API changes.
+4. Invoke **[frontend-developer]** for UI changes.
 
-## Step 3: [Action Name]
+## 4. Phase III: Verification (The "QA" Phase)
 
-[Detailed instructions for this step]
+1. Invoke **[qa-tester]** to run test suite.
+2. Verify all tests pass.
 ```
 
-## Calling Other Workflows
+## 5. Advanced Orchestration Patterns
 
-Chain workflows together:
+### Chaining Workflows
+
+Don't build monoliths. Compose small, focused workflows.
 
 ```markdown
-## Step 4: Deploy
+## Step 5: Deployment
 
 Call /deploy-staging
 ```
 
-## Agent-Generated Workflows
+### Dynamic Branching (via Logic)
+
+Workflows are linear, but the _Agent_ is dynamic. Use logic in steps:
+
+```markdown
+## Step 2: Determine Path
+
+IF requirements are unclear:
 
-After performing a task manually, ask agent to formalize it:
+- Call [business-analysis]
+  ELSE:
+- Proceed to Step 3
+```
 
-> "Create a workflow from our conversation about deploying to production"
+## 6. Maintenance & KPI
 
-## Best Practices
+Treat workflows like products.
 
-1. **Clear step names** - Describe the action in step title
-2. **Atomic steps** - One logical action per step
-3. **Include verification** - Add steps to confirm success
-4. **Document prerequisites** - State what's needed before running
+- **Review**: Does the workflow still match how the team works?
+- **Optimize**: Are we stopping too often? (Add `// turbo`). Are we breaking things? (Add Checkpoints).
+- **Refactor**: If a workflow steps become too complex, extract them into a dedicated Skill or a Sub-workflow.

package/.agent/skills/skill-creator/SKILL.md

@@ -60,10 +60,24 @@ Markdown instructions for the agent. Keep under **5000 tokens** for optimal cont
 
 Include:
 
-- Step-by-step workflows
+- **Tool Usage Standards**: Standard patterns for using Antigravity tools (`run_command`, `read_file`) within this domain.
+- Step-by-step workflows (Procedures, not Lifecycle Workflows)
 - Code examples
 - Edge cases and troubleshooting
 
+## Skill Design Principles
+
+**Strict Separation of Concerns**:
+
+- **Skill = Knowledge**: Capabilities, Standards, Best Practices, Reference Data.
+- **Workflow = Process**: Steps, Sequences, Lifecycles, Timelines.
+
+> [!WARNING]
+> **Do NOT embed Workflows in Skills.**
+>
+> - ❌ Bad: A `backend-developer` skill defining a "Feature Implementation" lifecycle.
+> - ✅ Good: A `backend-developer` skill defining "API Design Standards" and asking the user to use a generic Workflow to execute it.
+
 ## Progressive Disclosure
 
 Skills use three-level loading to manage context efficiently:
@@ -88,29 +102,12 @@ Skills use three-level loading to manage context efficiently:
 Use available tools to understand the full picture:
 
 1. **Search tools**: Use `search_web`, `read_url_content` to research official documentation
-2. **MCP servers**: Query relevant MCP servers (e.g., `context7` for library docs) if available
-3. **Codebase analysis**: Use `grep_search`, `find_by_name` to understand existing patterns
-
-**Use MCP Sequential Thinking for complex analysis:**
-
-For complex problems, use `mcp_sequential-thinking_sequentialthinking` to:
-
-- Break down problems into reasoning steps
-- Consider multiple angles, revise if needed
-- Generate hypotheses and verify step-by-step
-- Ensure no edge cases are missed
-
-```
-Thought 1: Identify core requirements
-Thought 2: Analyze dependencies
-Thought 3: Consider edge cases
-...
-Final: Synthesize conclusions
-```
+2. **Codebase analysis**: Use `grep_search`, `find_by_name` to understand existing patterns
 
 **Analyze step-by-step:**
 
 - What are the core capabilities needed?
+- **What standard Antigravity tools are most relevant?** (e.g., read_file for docs, run_command for CLI)
 - What are common use cases and edge cases?
 - What scripts or references would be reusable?
 
@@ -196,6 +193,7 @@ Instead of generic "What constraints?", ask specific questions like:
 
 - What is the specific domain? (frontend, backend, devops, AI, etc.)
 - What tech stack or frameworks are involved?
+- **What standard tool patterns apply?** (e.g., File system ops vs Command line ops)
 - What constraints must be followed? (time, resources, team size)
 
 ### Phase 3: Scope (Define Boundaries)

package/.agent/skills/skill-creator/assets/skill-questionnaire.md

@@ -73,6 +73,14 @@
 
 <!-- Options: junior, senior, expert (20+ years) -->
 
+### Design Principle: Separation of Concerns
+
+<!-- Reminder:
+- Skill = Knowledge (Capabilities, Standards, Best Practices)
+- Workflow = Process (Steps, Sequences, Lifecycles)
+Do NOT ask for "Process" definitions here. Focus on "Knowledge".
+-->
+
 ### Which best practices must be followed?
 
 <!-- Example: "Follow Testing Trophy pattern, AAA structure for tests" -->

package/.agent/workflows/bootstrap.md

@@ -0,0 +1,96 @@
+---
+description: Sets up project structure, installs dependencies, and configures environment based on architectural specs.
+---
+
+# Bootstrap Workflow
+
+> [!IMPORTANT]
+> **Prerequisite**: Ensure SDD exists in `docs/030-Specs/Architecture/`.
+
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                          | When to Use                        |
+| :-------------------------------- | :--------------------------------- |
+| `mcp_context7_resolve-library-id` | Find correct package names         |
+| `mcp_context7_query-docs`         | Research installation/config steps |
+
+---
+
+## Step 1: Framework Initialization & Structure
+
+// turbo
+
+1. **Invoke `[lead-architect]` skill** to:
+   - Define the project root structure (Monorepo vs Polyrepo)
+   - Initialize the base project (e.g., `git init`, `npx create-next-app`)
+   - Create the directory skeleton based on SDD
+2. **WAIT** for initialization
+
+---
+
+## Step 2: Maintenance & Quality Engineering Tools
+
+// turbo
+
+> 💡 **Role**: DevOps Engineer ensures the "Development Experience" (DX) is solid.
+
+1. **Invoke `[devops-engineer]` skill** to install & configure:
+   - **Quality Tools**: ESLint, Prettier, TypeScript config
+   - **Git Hooks**: Husky, Lint-staged, Commitlint
+   - **CI/CD**: Github Actions (basic build/test)
+2. Verify: Run `npm run lint` and ensure hooks fire on commit.
+
+---
+
+## Step 3: Frontend Setup
+
+// turbo
+
+> 💡 **Role**: Frontend Developer manages the UI/Client side.
+
+1. **Invoke `[frontend-developer]` skill** to:
+   - **UI Ecosystem**: Install TailwindCSS, Radix/Shadcn, Framer Motion
+   - **State Manager**: Zustand/Jotai/Redux
+   - **Structure**: Setup `src/components`, `src/hooks`, `src/pages` (or `app`)
+   - **Assets**: Configure font loaders, image optimization
+2. **WAIT** for installation
+
+---
+
+## Step 4: Backend Setup
+
+// turbo
+
+> 💡 **Role**: Backend Developer manages the Data/Server side.
+
+1. **Invoke `[backend-developer]` skill** to:
+   - **Database**: Setup Prisma/Drizzle/Supabase client
+   - **API**: Configure API routes/Server Actions
+   - **Validation**: Install Zod/Valibot
+   - **Environment**: Create `.env.example` and validate `.env` keys
+2. **WAIT** for installation
+
+---
+
+## Step 5: Final Validation
+
+// turbo
+
+1. **Invoke `[devops-engineer]` skill** to:
+   - Run full build `npm run build`
+   - Test Type-checking `tsc --noEmit`
+2. **Invoke `[product-manager]`** to update Roadmap status to "In Progress"
+
+---
+
+## Quick Reference
+
+| Step | Skill              | Action                      |
+| :--- | :----------------- | :-------------------------- |
+| 1    | lead-architect     | Init Framework & Structure  |
+| 2    | devops-engineer    | Husky, Linter, CI/CD        |
+| 3    | frontend-developer | Tailwind, Components, State |
+| 4    | backend-developer  | DB, API, Env                |
+| 5    | devops-engineer    | Final Build Check           |

package/.agent/workflows/brainstorm.md

@@ -0,0 +1,81 @@
+---
+description: Analyze ideas with the user and create preliminary high-level documents (Roadmap, PRD).
+---
+
+# Brainstorm Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Read `.agent/rules/documents.md` before creating any document.
+
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                            | Example                           |
+| :------------------------------------------- | :----------------------------------------------------- | :-------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Analyze requirements, feature dependencies, trade-offs | Break down ambiguous requests     |
+| `mcp_context7_resolve-library-id`            | Find library ID before querying                        | "mermaid js"                      |
+| `mcp_context7_query-docs`                    | Research tech stack options, diagram syntax            | "Mermaid sequence diagram syntax" |
+
+---
+
+## Document Priority Order
+
+```
+Priority 0: Roadmap       ← Project Planning & Timeline
+Priority 1: PRD           ← Strategic Overview
+```
+
+---
+
+## Step 0: Clarification & Understanding
+
+**Role: Product Manager**
+
+> [!NOTE]
+> This step is **MANDATORY**. Do NOT proceed without user confirmation.
+
+> 💡 **MCP**: Use `sequential-thinking` to analyze ambiguous or complex requests
+
+1. **Invoke `[product-manager]` skill** to:
+   - Summarize understanding
+   - Create clarification questions
+2. Create `clarification-questions.md` artifact
+3. **WAIT** for user to review and confirm
+
+---
+
+## Step 1: Create Roadmap
+
+// turbo
+
+> 💡 **MCP**: Use `sequential-thinking` for phased planning and risk assessment
+
+1. **Invoke `[product-manager]` skill** to draft:
+   - Project timeline and milestones
+   - Phase breakdown (MVP, v1.0, v2.0)
+   - Key deliverables per phase
+2. Create `draft-roadmap.md` artifact
+3. After approval → Save to `docs/010-Planning/Roadmap-{ProjectName}.md`
+4. **WAIT** for user response
+
+---
+
+## Step 2: Create PRD
+
+// turbo
+
+1. **Invoke `[product-manager]` skill** to draft:
+   - Business objectives and success metrics
+   - Target audience/user personas
+   - Feature prioritization (MoSCoW)
+2. Create `draft-prd.md` artifact
+3. After approval → Save to `docs/020-Requirements/PRD-{ProjectName}.md`
+4. **WAIT** for user response
+
+---
+
+## Step 3: Transition to Documentation
+
+1. Present summary of created artifacts (Roadmap, PRD).
+2. Suggest next step: Run `/documentation` to generate detailed specifications (SDD, Epics, Stories).

package/.agent/workflows/custom-behavior.md

@@ -0,0 +1,64 @@
+---
+description: Workflow for safely customizing Agent rules and workflows with impact analysis and user confirmation.
+---
+
+# Custom Behavior Workflow
+
+## Tool Usage Guidelines
+
+| Tool            | When to Use                                          | Example Query                                                   |
+| --------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| `find_by_name`  | Step 1: To find if a rule/workflow already exists    | `Pattern="*security*", SearchDirectory=".agent/rules"`          |
+| `view_file`     | Step 2: To read the existing content for comparison  | `AbsolutePath="/.../.agent/rules/security.md"`                  |
+| `notify_user`   | Step 3: To present analysis and ask for confirmation | `Message="I found an existing rule. Do you want to overwrite?"` |
+| `write_to_file` | Step 4: To create or overwrite the file              | `Overwrite=true`                                                |
+
+## Step 1: Identification & Search
+
+// turbo
+
+> 💡 **Tip**: Don't assume the file doesn't exist. Always search first.
+
+1.  Analyze the user's request to identify the _intent_ (e.g., "Add stricter linting", "Skip tests in deployment").
+2.  Search for existing Rules or Workflows that might already cover this.
+    - Rules: search in `.agent/rules/`
+    - Workflows: search in `.agent/workflows/`
+
+## Step 2: Impact Analysis
+
+> 💡 **Tip**: If a file exists, you MUST read it and compare it with the request.
+
+**Condition A: Target does NOT exist:**
+
+1.  Verify if a template exists in `.agent/assets/` or `references/` that could be used as a base.
+2.  Draft the new content in your memory.
+
+**Condition B: Target ALREADY exists:**
+
+1.  **Read** the current content of the file.
+2.  **Compare** the User's request vs the Current Content.
+3.  **Identify Conflicts**:
+    - Will this break existing constraints?
+    - Is this a "Breaking Change" or just an "Enhancement"?
+4.  **Formulate Recommendation**:
+    - _Adapt_: "I recommend creating a new file `custom-X.md` to avoid breaking standard X."
+    - _Override_: "This helps matches your specific need, but removes the safety check Y."
+
+## Step 3: User Confirmation
+
+> 💡 **Tip**: You must be explicit about what will change.
+
+1.  **Notify User** with a summary of your analysis.
+    - If **New**: "I will create a new rule [filename] that [does X]."
+    - If **modifying**: "I will modify [filename]. \n**Current**: [Summary of old]\n**Proposed**: [Summary of new]\n**Impact**: [Warning about side effects]"
+2.  **WAIT** for user approval.
+
+## Step 4: Execution
+
+1.  Perform the file operation (`write_to_file` or `replace_file_content`).
+2.  **Validate**: Read the file back to ensure syntax is correct (Markdown/YAML frontmatter).
+3.  **Register**: If it's a rule, remind the user if they need to manually activate it (unless it's `always_on`).
+
+## Step 5: Verification
+
+1. Check if the customization works as expected (if possible, by running a dry-run or asking user to test).