grimoire-framework 1.0.0

package/.grimoire/development/tasks/blocks/context-loading.md

@@ -0,0 +1,110 @@
+# Block: Context Loading
+
+> **Block ID:** `context-loading`
+> **Version:** 1.0.0
+> **Type:** Reusable Include Block
+
+## Purpose
+
+Load grimoire project context before task execution. Provides git state, gotchas filtered by category, technical preferences, and core configuration.
+
+## Input
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `category` | string | No | `null` | Filter gotchas by category (e.g., `supabase`, `frontend`, `auth`) |
+| `include_git` | boolean | No | `true` | Include git status and recent commits |
+| `include_gotchas` | boolean | No | `true` | Load gotchas from memory |
+| `include_preferences` | boolean | No | `true` | Load technical preferences |
+
+## Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `git.status` | string | Output of `git status --short` |
+| `git.recentCommits` | string[] | Last 5 commits (oneline format) |
+| `gotchas` | Gotcha[] | Filtered gotchas relevant to current task |
+| `preferences` | object | Technical preferences from data file |
+| `config` | object | Core configuration keys |
+
+## Execution Steps
+
+```yaml
+steps:
+  - name: Load Git Context
+    condition: include_git == true
+    actions:
+      - run: git status --short
+      - run: git log --oneline -5
+    output: git.status, git.recentCommits
+
+  - name: Load Gotchas
+    condition: include_gotchas == true
+    actions:
+      - read: .grimoire/gotchas.json
+      - filter: by category if provided
+    output: gotchas
+
+  - name: Load Technical Preferences
+    condition: include_preferences == true
+    actions:
+      - read: .grimoire/data/technical-preferences.md
+    output: preferences
+
+  - name: Load Core Config
+    actions:
+      - read: .grimoire/core-config.yaml
+      - extract: devLoadAlwaysFiles, project.*, deployment.*
+    output: config
+```
+
+## Usage
+
+### Include in Task File
+
+```markdown
+<!-- Include: blocks/context-loading.md -->
+<!-- Parameters: category=supabase -->
+```
+
+### Programmatic Usage
+
+```javascript
+const { loadContext } = require('.grimoire/utils/context-loader');
+
+const context = await loadContext({
+  category: 'supabase',
+  include_git: true,
+  include_gotchas: true,
+  include_preferences: true
+});
+
+// Access loaded context
+console.log(context.git.status);
+console.log(context.gotchas);
+console.log(context.config.devLoadAlwaysFiles);
+```
+
+## Files Accessed
+
+| File | Purpose |
+|------|---------|
+| `.grimoire/gotchas.json` | Known issues and workarounds |
+| `.grimoire/data/technical-preferences.md` | User-defined patterns |
+| `.grimoire/core-config.yaml` | Project configuration |
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| File not found | Log warning, continue with empty value |
+| Parse error | Log error, use empty default |
+| Git not available | Skip git context, log info |
+
+## Notes
+
+- Block executes in <2 seconds for typical projects
+- Gotchas are cached per session to avoid repeated reads
+- Git commands are non-blocking and fail gracefully
+
+

package/.grimoire/development/tasks/blocks/execution-pattern.md

@@ -0,0 +1,122 @@
+# Block: Execution Pattern
+
+> **Block ID:** `execution-pattern`
+> **Version:** 1.0.0
+> **Type:** Reusable Include Block
+
+## Purpose
+
+Define how agent waiting works with the Task tool. Provides patterns for sequential and parallel execution, plus anti-patterns to avoid.
+
+## Input
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `execution_type` | string | No | `sequential` | One of: `sequential`, `parallel`, `mixed` |
+| `parallel_count` | number | No | `3` | Number of parallel agents (only for parallel/mixed) |
+
+## Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `understanding` | string | How blocking mechanism works |
+| `pattern` | string | Code pattern for the execution type |
+| `anti_patterns` | string[] | What to avoid |
+
+## Core Content
+
+### How Agent Waiting Works
+
+The `Task` tool has **native blocking behavior** - it automatically waits for the agent to complete before returning. You do NOT need any manual waiting mechanism.
+
+### Sequential Execution
+
+```
+# Task tool WITHOUT run_in_background = BLOCKS until agent completes
+Task(prompt: "...", subagent_type: "general-purpose", ...)
+# ↑ This line does NOT return until the agent finishes
+# ↓ When execution reaches here, the agent is DONE
+TaskUpdate(taskId: "X", status: "completed")
+```
+
+### Parallel Execution
+
+```
+# Spawn ALL N agents in a SINGLE message with run_in_background: true
+Task(prompt: "agent 1...", run_in_background: true)  → returns task_id_1
+Task(prompt: "agent 2...", run_in_background: true)  → returns task_id_2
+Task(prompt: "agent N...", run_in_background: true)  → returns task_id_N
+
+# Then wait for each using TaskOutput (blocks until agent completes)
+TaskOutput(task_id: "id_1", block: true)
+TaskOutput(task_id: "id_2", block: true)
+TaskOutput(task_id: "id_N", block: true)
+```
+
+### Mixed Execution
+
+Combine sequential phases with parallel phases:
+1. Sequential: Use blocking Task calls
+2. Parallel: Spawn with `run_in_background: true`, collect with `TaskOutput`
+3. Sequential: Resume after all parallel agents complete
+
+## Anti-Patterns (NEVER DO THIS)
+
+```
+# ❌ WRONG: Sleep loops
+Bash("sleep 30")
+Bash("sleep 60")
+
+# ❌ WRONG: Polling loops
+while not done:
+    Bash("sleep 10")
+    check_if_file_exists()
+
+# ❌ WRONG: Periodic file checking
+Read("output_file")  # hoping it appeared
+Bash("sleep 30")
+Read("output_file")  # checking again
+
+# ❌ WRONG: Asking teammate for status via SendMessage polling
+SendMessage("hey, are you done yet?")
+```
+
+**The Task tool handles ALL waiting automatically. Trust the blocking mechanism.**
+
+## Usage
+
+### Include in Skill File
+
+```markdown
+<!-- Include: blocks/execution-pattern.md -->
+<!-- Parameters: execution_type=mixed, parallel_count=4 -->
+```
+
+### Direct Reference
+
+```markdown
+## Execution Pattern (CRITICAL)
+
+See: `.grimoire/development/tasks/blocks/execution-pattern.md`
+
+This skill uses **{execution_type}** execution with {parallel_count} parallel agents.
+```
+
+## Files Accessed
+
+None - this is a reference/documentation block.
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| Invalid execution_type | Default to `sequential` |
+| parallel_count < 1 | Default to `3` |
+
+## Notes
+
+- Block provides understanding, not executable code
+- Anti-patterns section prevents common mistakes
+- Found in 8+ skills with 98% similarity
+- Total lines saved: ~35 lines × 8 skills = 280 lines
+

package/.grimoire/development/tasks/blocks/finalization.md

@@ -0,0 +1,123 @@
+# Block: Finalization
+
+> **Block ID:** `finalization`
+> **Version:** 1.0.0
+> **Type:** Reusable Include Block
+
+## Purpose
+
+End a multi-agent workflow by presenting summary to user, cleaning up team resources, and providing next steps. Used at the end of orchestrator skills after all phases complete.
+
+## Input
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `workflow_name` | string | Yes | - | Display name of the workflow (e.g., "Enhance Workflow", "Deep Strategic Planning") |
+| `slug` | string | Yes | - | Project/decision slug in snake_case |
+| `artifacts_list` | object[] | Yes | - | Array of `{ path, description }` for generated files |
+| `summary_data` | object | No | `{}` | Workflow-specific summary (e.g., `{ epic_title, stories_count }`) |
+| `next_steps` | string[] | Yes | - | Array of recommended next actions |
+| `team_name` | string | Yes | - | Team name for cleanup (e.g., "enhance-{slug}") |
+
+## Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `summary_presented` | boolean | User was shown final summary |
+| `agents_shutdown` | boolean | All agents received shutdown_request |
+| `team_deleted` | boolean | TeamDelete executed successfully |
+
+## Core Content
+
+### Step 1: Present Summary to User
+
+Display a formatted summary containing:
+- All generated artifact paths with descriptions
+- Workflow-specific highlights (from `summary_data`)
+- Next steps as numbered list
+
+### Step 2: Cleanup Agents
+
+```
+# For each remaining agent in the team:
+SendMessage(
+  type: "shutdown_request",
+  recipient: "{agent_name}",
+  content: "Workflow complete. Shutting down."
+)
+```
+
+### Step 3: Delete Team
+
+```
+# After all agents acknowledge shutdown:
+TeamDelete(team_name: "{team_name}")
+```
+
+### Summary Template
+
+```markdown
+## {workflow_name} Complete: {slug}
+
+### Generated Artifacts
+{foreach artifact in artifacts_list}
+- `{artifact.path}` - {artifact.description}
+{/foreach}
+
+### Summary
+{workflow-specific summary from summary_data}
+
+### Next Steps
+{foreach step, index in next_steps}
+{index + 1}. {step}
+{/foreach}
+```
+
+## Usage
+
+### Include in Skill File
+
+```markdown
+<!-- Include: blocks/finalization.md -->
+<!-- Parameters:
+  workflow_name=Enhance Workflow
+  slug={project_slug}
+  team_name=enhance-{slug}
+-->
+```
+
+### Programmatic Usage
+
+```javascript
+const finalize = async ({ workflow_name, slug, artifacts_list, summary_data, next_steps, team_name }) => {
+  // 1. Present summary
+  presentSummary({ workflow_name, slug, artifacts_list, summary_data, next_steps });
+
+  // 2. Shutdown agents
+  const agents = await getTeamAgents(team_name);
+  for (const agent of agents) {
+    await sendShutdownRequest(agent);
+  }
+
+  // 3. Delete team
+  await teamDelete(team_name);
+
+  return { summary_presented: true, agents_shutdown: true, team_deleted: true };
+};
+```
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| Agent shutdown timeout | Log warning, continue with TeamDelete |
+| TeamDelete fails | Log error, report to user |
+| Missing artifacts | List as "not generated" in summary |
+
+## Notes
+
+- Block executes after ALL phases complete
+- Agents should save their work before receiving shutdown_request
+- TeamDelete is the final cleanup step
+- Found in 2+ orchestrator skills with 95%+ similarity
+- Total lines saved: ~40 lines × N skills

package/.grimoire/development/tasks/bootstrap-shadcn-library.md

@@ -0,0 +1,288 @@
+# Bootstrap Shadcn/Radix Component Library
+
+> Task ID: atlas-bootstrap-shadcn  
+> Agent: Atlas (Design System Builder)  
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (grimoire Task Format V1.0)
+
+```yaml
+task: bootstrapShadcnLibrary()
+responsável: Uma (Empathizer)
+responsavel_type: Agente
+atomic_layer: Config
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .grimoire/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .grimoire/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .grimoire/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 2-10 min (estimated)
+cost_estimated: $0.001-0.008
+token_usage: ~800-2,500 tokens
+```
+
+**Optimization Notes:**
+- Validate configuration early; use atomic writes; implement rollback checkpoints
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Install and curate a Shadcn UI component library leveraging Tailwind v4, Radix primitives, and project design tokens. Establish shared utilities (`cn`, `cva`), Spinner/loading patterns, and documentation scaffold.
+
+## Prerequisites
+
+- Tailwind v4 configured with tokens (`@theme` + dark mode)
+- React/Next.js project with TypeScript
+- Node.js ≥ 18
+- Storybook (optional but recommended)
+
+## Workflow
+
+1. **Initialize Shadcn CLI**
+   ```bash
+   npx shadcn@latest init
+   ```
+   - Configure paths (`components`, `lib/utils.ts`)
+   - Enable TypeScript + Tailwind + Radix defaults
+
+2. **Install Core Utilities**
+   ```bash
+   npx shadcn@latest add button input card textarea badge skeleton spinner
+   ```
+   - Ensure `cn` helper uses `clsx` + `tailwind-merge`
+   - Add `Spinner` component for loading states (if not provided by template)
+
+3. **Map to Tokens**
+   - Replace hardcoded colors with semantic token classes (`bg-primary`, etc.)
+   - Align spacing/typography with design system scale
+   - Add dark mode variants (`dark:bg-background`)
+
+4. **Radix Integration**
+   - Install Radix primitives as required (`@radix-ui/react-slot`, etc.)
+   - Verify accessibility attributes and focus management remain intact
+
+5. **Variant & Utility Enhancements**
+   - Extend `cva` definitions to match project variants (density, destructive, ghost)
+   - Add shared loading pattern (Spinner + `isLoading` prop)
+   - Introduce compound variants for icon buttons, destructive actions
+
+6. **Documentation & Storybook**
+   - Create MDX or markdown docs for each component (`docs/components`)
+   - Optional: Add Storybook stories using auto-generated stories from `tasks/build-component`
+
+7. **Update State**
+   - Append to `.state.yaml` (`tooling.shadcn`) with components installed, timestamp
+   - Record any local overrides or follow-up actions
+
+## Deliverables
+
+- Populated `components/ui/` directory with Shadcn components
+- Updated `lib/utils.ts` (`cn`, `formatNumber`, etc. if needed)
+- Component documentation & Storybook stories (optional)
+- `.state.yaml` entries for `tooling.shadcn`
+
+## Success Criteria
+
+- [ ] Shadcn CLI initialized with Tailwind v4-compatible paths
+- [ ] Core components (button/input/card/etc.) installed and tokenized
+- [ ] `cn` helper + `class-variance-authority` configured
+- [ ] Spinner/loading pattern standardized across components
+- [ ] Documentation/Storybook updated with usage examples
+- [ ] `.state.yaml` reports bootstrap timestamp and component list
+
+## Error Handling
+
+- **CLI install failure**: Delete partial files, rerun `npx shadcn@latest init`
+- **Radix import mismatch**: Align versions with lockfile, reinstall packages
+- **Token mismatch**: Regenerate Tailwind classes or add missing semantic tokens
+- **Storybook build failure**: Update Storybook to latest (v8+) and re-run
+
+## Notes
+
+- Prefer named exports (`export { Button }`) for tree-shaking
+- Maintain parity between Shadcn variants and design token aliases
+- Document manual updates (Shadcn is copy/paste — no automatic updates)
+- Schedule regular audits to pull upstream improvements intentionally
+
+