gemini-kit Documentation

The scripts/ directory contains automation scripts designed to power agent workflows, manage compound engineering workflows, handle knowledge management, and perform repository maintenance. These scripts are categorized into several functional areas:

• Workflow Core: Logging and pre-push checks.
• Compound System: Knowledge search, metrics, and validation.
• Todo Management: Creating, completing, and auditing todos.
• Maintenance: Archiving, log rotation, and environment management.
• Metrics & Instrumentation: Telemetry, scoring, and health validation.
• Utilities: Architecture and lifecycle management.

The compound-docs skill is used to manage solution documentation in docs/solutions/ to ensure knowledge persistence across sessions. Use this skill when you solve a problem and want to ensure the solution can be found and reused later.

Core Workflows:

• Document a solution: Follow the /compound workflow.
• Find existing solutions: Use the searching techniques described below.
• Promote to pattern: Follow the pattern promotion process for recurring issues.
• Validate schema: Ensure all solution files adhere to the YAML frontmatter requirements.

Gemini-Kit is organized into several functional directories that separate agent logic, tool implementations, and configuration:

• agents/: Contains the definitions for the 15 AI agents.
• commands/: Contains 42 slash commands defined in .toml format.
• hooks/: Contains lifecycle hooks (e.g., before-tool, after-tool).
• src/tools/: Contains the TypeScript implementations for Model Context Protocol (MCP) tools.
• skills/: Contains modular agent capabilities.
• docs/: Contains system architecture, ADRs (Architecture Decision Records), Knowledge Base solutions, and multi-session specifications.
• scripts/: Contains automation scripts.
• plans/ and todos/: Used for tracking implementation plans and work items.

The Solutions Knowledge Base provides persistent storage for solved problems and reusable patterns. It is designed to capture symptoms, root cause analysis, and prevention strategies to ensure problems are not repeated across sessions.

Key components include:

• patterns/: A collection of 23 critical patterns and anti-patterns that agents should consult before generating code.
• integrations/: Guides and solutions for specific integrations.
• templates/: Standardized templates (solution-template.md, exploration-template.md) for documenting new problems or explorations.
• schema.yaml: A YAML validation schema used to ensure solution documents contain required fields, correct problem types, severity levels, and component types.

Gemini-Kit documentation is organized into several specialized directories to help you understand the system, its design decisions, and its implementation patterns:

• architecture/: Contains system architecture documentation.
• decisions/: Contains Architecture Decision Records (ADRs).
• explorations/: Contains deep research artifacts.
• solutions/: Serves as a Knowledge Base for persistent solutions.
• specs/: Contains multi-session specifications.

For specific technical guidance, refer to the API Reference for MCP tools and extension APIs, or the Critical Patterns guide for 23 recommended implementation patterns.

The Knowledge Base serves as the persistent storage for solved problems within the project. It uses a structured directory to ensure solutions are searchable and consistent.

Directory Structure:

• docs/solutions/schema.yaml: The validation schema for all solutions.
• docs/solutions/solution-template.md: The template to use when documenting new solutions.
• docs/solutions/patterns/critical-patterns.md: A collection of 23 anti-patterns to avoid.
• docs/solutions/{category}/{solution}.md: Individual solution files organized by category.

Key Features:

• YAML frontmatter: Used for making solutions searchable.
• Categorization: Solutions are mapped to specific problem types.
• Schema validation: Ensures all new documentation follows the required format.

Define an app_role enum (e.g., fund_manager, investor) and store it in a profiles table linked to auth.users. Use RLS policies to check the user's role in the profiles table to grant or restrict access to sensitive tables.

-- Role enum
CREATE TYPE app_role AS ENUM ('fund_manager', 'investor');

-- Profiles with role
CREATE TABLE profiles (
    id UUID PRIMARY KEY REFERENCES auth.users(id),
    role app_role NOT NULL DEFAULT 'investor'
);

-- Role-based policy
CREATE POLICY "Fund Managers can view all"
ON sensitive_table FOR SELECT TO authenticated
USING (
    EXISTS (
        SELECT 1 FROM profiles
        WHERE profiles.id = auth.uid()
        AND profiles.role = 'fund_manager'
    )
);

To ensure deferred work remains visible to automated workflows, do not leave unchecked tasks solely within implementation plans or walkthroughs. Every unchecked - [ ] in an artifact that represents actionable future work must have a corresponding dedicated file in the todos/ directory.

Example Workflow: Instead of leaving a task in implementation_plan.md:

## Future Work
- [ ] Investigate async driver

Create a specific file: todos/001-ready-p2-investigate-async-driver.md