|
1 | | -# Gemini CLI Starter Pack |
| 1 | +# Gemini CLI Opinionated Framework |
2 | 2 |
|
3 | | -This is a specialized starter repository for building new projects with a focus on **safe and coherent AI-assisted coding**. It's pre-configured for the **Gemini CLI** with advanced hooks, commands, agents, and skills to ensure a high-quality engineering lifecycle. |
| 3 | +This is a highly opinionated repository framework designed to transform how developers work with AI agents, specifically optimized for the [Gemini CLI](https://github.com/google/gemini-cli). It’s not just a collection of files; it’s a **cognitive partnership model** that enforces rigorous engineering standards, strategic planning, and continuous validation. |
4 | 4 |
|
5 | | -## Why Use This Starter Pack? |
| 5 | +While tailored for Gemini CLI, the core philosophy—folders like `.gemini/`, files like `GEMINI.md`, and the journaling/task-tracking workflow—can be adapted to any AI agent by simply renaming the relevant files and folders (e.g., to `.cursor/` or `.aider/`). |
6 | 6 |
|
7 | | -* **Strategic Planning:** Forces a "Research -> Strategy -> Execution" cycle for non-trivial changes. |
8 | | -* **Validation-First:** Integrated `makefile` hooks ensure code passes linting and tests before being committed. |
9 | | -* **Deep Context:** Pre-configured with a robust `deep-research` skill for complex technical investigations. |
10 | | -* **Auditability:** Automated journaling (`journal/`) and changelog (`CHANGELOG.md`) management. |
11 | | -* **Specialized Agents:** Includes sub-agents like `online_researcher` for high-signal web investigations. |
| 7 | +## The Core Philosophy: AI as a Senior Partner |
12 | 8 |
|
13 | | ---- |
| 9 | +In this framework, the AI agent is not a "code generator" or a "copilot". It is a **Senior Architect and Critical Thinking Partner**. |
14 | 10 |
|
15 | | -## Getting Started |
16 | | - |
17 | | -### 1. Fork and Clone |
18 | | -Fork this repository and clone it to your local machine: |
19 | | -```bash |
20 | | -git clone https://github.com/your-username/your-new-project.git |
21 | | -cd your-new-project |
22 | | -``` |
23 | | - |
24 | | -### 2. Initialize the Project |
25 | | -Update the `GEMINI.md` and `package.json` (or equivalent) with your specific project details. |
26 | | -```bash |
27 | | -# Example: Run the onboard command |
28 | | -gemini /onboard |
29 | | -``` |
30 | | - |
31 | | -### 3. Usage |
32 | | -Use the Gemini CLI to interact with the repository. |
33 | | -```bash |
34 | | -gemini /research "how to implement X in this stack" |
35 | | -gemini /commit |
36 | | -``` |
| 11 | +* **Critical Feedback First:** The agent is instructed to challenge unsafe, redundant, or poorly conceived ideas *before* writing a single line of code. |
| 12 | +* **Research -> Plan -> Execute:** Every non-trivial change follows a strict lifecycle. The agent first researches the context, proposes a detailed plan, waits for your explicit approval, and only then begins implementation. |
| 13 | +* **Validation-Always:** The framework uses `make` as a source of truth. The agent is hooked into the `makefile` to ensure that every change is validated (linted and tested) before being finalized. |
37 | 14 |
|
38 | | ---- |
| 15 | +## The Workflow: Start Fresh, Move Fast |
39 | 16 |
|
40 | | -## Core Features |
| 17 | +To use this framework for a new project, follow these steps: |
41 | 18 |
|
42 | | -### 1. Advanced Commands (`.gemini/commands/`) |
43 | | -* **/commit:** Analyzes changes, groups them into logical features/bugfixes, and commits with Conventional Commits. |
44 | | -* **/research:** Invokes the `deep-research` skill for exhaustive online and codebase investigations. |
45 | | -* **/onboard:** Assists in setting up the project and understanding its structure. |
46 | | -* **/maintainance:** Deep analysis and planning for codebase refactoring or cleanup. |
47 | | -* **/release:** Handles version bumping and release documentation. |
48 | | -* **/docs:** Automates the generation and maintenance of project documentation. |
| 19 | +1. **Clone the Repo:** |
| 20 | + ```bash |
| 21 | + git clone https://github.com/apiad/starter.git my-new-project |
| 22 | + cd my-new-project |
| 23 | + ``` |
| 24 | +2. **Reset for a New Project:** |
| 25 | + Remove the existing history and documentation to start with a blank slate: |
| 26 | + ```bash |
| 27 | + rm -rf .git README.md CHANGELOG.md journal/*.md |
| 28 | + git init |
| 29 | + ``` |
| 30 | +3. **Scaffold Your Stack:** |
| 31 | + Use the built-in `/scaffold` command to initialize your project with modern tooling (Python/uv, TS/npm, Rust/cargo, etc.): |
| 32 | + ```bash |
| 33 | + gemini /scaffold |
| 34 | + ``` |
| 35 | + The agent will ask you about your preferred stack, architecture, and tools, then generate the project structure and a compatible `makefile`. |
49 | 36 |
|
50 | | -### 2. Specialized Agents (`.gemini/agents/`) |
51 | | -* **online_researcher:** A senior research specialist that decomposes complex queries, performs deep web searches, and synthesizes data with full citations. |
| 37 | +## The Hook System: Staying in Sync |
52 | 38 |
|
53 | | -### 3. Agent Skills (`.gemini/skills/`) |
54 | | -* **deep-research:** A robust, iterative skill that tracks progress via `research.plan.md`, aggregates raw data in `research.dump.md`, and synthesizes it into a section-by-section `report.md`. |
| 39 | +The framework uses a robust hook system (`.gemini/hooks/`) that synchronizes the agent with your project state: |
55 | 40 |
|
56 | | ---- |
| 41 | +* **`session_start.py`**: Initializes the environment and greets you. |
| 42 | +* **`welcome.py`**: Provides a high-level summary of the current project state and available commands. |
| 43 | +* **`enforce_journal.py`**: Ensures a journal entry exists for the current date, maintaining an audit trail of decisions and progress. |
| 44 | +* **`check_make.py`**: Automatically runs `make` (minimal lint+test) after critical agent actions to prevent regressions. |
| 45 | +* **`log_model_output.py`**: Records agent outputs for debugging and session review. |
57 | 46 |
|
58 | | -## Workflow & Hooks Lifecycle |
| 47 | +## Powerful Commands |
59 | 48 |
|
60 | | -The project enforces a strict engineering standard through its **Hook System** (`.gemini/hooks/`): |
| 49 | +The `.gemini/commands/` directory defines specialized workflows: |
61 | 50 |
|
62 | | -1. **Session Start (`session_start.py`):** Orchestrates session initialization and greets the developer. |
63 | | -2. **Welcome & Context (`welcome.py`):** Provides a high-level summary of the current project state. |
64 | | -3. **Journal Enforcement (`enforce_journal.py`):** Ensures that a journal entry exists for the current date, maintaining an audit trail of decisions. |
65 | | -4. **Make Validation (`check_make.py`):** Automatically runs `make lint` and `make test` before critical AI actions to prevent regressions. |
66 | | -5. **Audit Logging (`log_model_output.py`):** Records agent outputs for debugging and session review. |
| 51 | +* **/scaffold**: Initializes a new project from scratch with modern standard practices. |
| 52 | +* **/task**: A unified command to `create`, `work` on, `report`, or `update` your project roadmap (`TASKS.md`). |
| 53 | +* **/research**: A robust 3-phase workflow (Planning -> Data Gathering via `researcher` agent -> Reporting via `reporter` agent) for exhaustive investigations. |
| 54 | +* **/commit**: Analyzes changes, groups them logically, and commits them one-by-one using Conventional Commits. |
| 55 | +* **/release**: Automates version bumping, `CHANGELOG.md` updates, and git tagging. |
| 56 | +* **/maintainance**: Performs deep analysis and proposes step-by-step refactoring plans. |
| 57 | +* **/docs**: Generates and maintains project documentation. |
| 58 | +* **/onboard**: Helps new developers (or the agent itself) understand the project structure. |
67 | 59 |
|
68 | | ---- |
| 60 | +## The Journaling Idea |
69 | 61 |
|
70 | | -## Development Standards |
| 62 | +Journaling is central to this framework. Every day you work on the project, a new entry is created in `journal/YYYY-MM-DD.md`. |
71 | 63 |
|
72 | | -As defined in `GEMINI.md`, the AI agent acts as a **Senior Architect and Critical Thinking Partner**. It is mandate-bound to: |
73 | | -* Critique unsafe or flawed proposals before implementation. |
74 | | -* Present a detailed strategy and seek approval for non-trivial changes. |
75 | | -* Enforce a clean "Research -> Strategy -> Execution" lifecycle. |
76 | | -* Prioritize modular, maintainable code over "just-in-case" complexity. |
| 64 | +* **Why?** It provides a persistent "memory" for the agent and a clear audit trail for you. When you start a new session, the agent reads the recent journals to understand exactly where you left off. |
| 65 | +* **Enforcement:** The `enforce_journal.py` hook ensures you never forget to document your progress. |
| 66 | + |
| 67 | +## Engineering Standards (GEMINI.md) |
| 68 | + |
| 69 | +The `GEMINI.md` file is the **"Soul" of the Agent**. It contains the core mandates that the agent must follow, including: |
| 70 | +* Critical cognitive partnership. |
| 71 | +* Strategic planning and approval. |
| 72 | +* Modern engineering standards (DRY, documentation, testing). |
| 73 | +* Rigorous tool validation. |
77 | 74 |
|
78 | 75 | --- |
79 | 76 |
|
80 | 77 | ## License |
81 | | -MIT (or as specified in your fork). |
| 78 | + |
| 79 | +MIT |
0 commit comments