Skip to content

Commit 97618e5

Browse files
apiadapiad
committed
docs: add comprehensive project documentation suite
1 parent 2090b90 commit 97618e5

4 files changed

Lines changed: 201 additions & 0 deletions

File tree

‎docs/deploy.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Installation & Setup
2+
3+
Getting the **Gemini CLI Opinionated Framework** up and running is an automated, interactive process. Whether you're starting a new project or integrating into an existing one, the `install.sh` script is your primary tool.
4+
5+
## 🚀 The Unified Installer
6+
7+
The fastest way to install or update the framework is to run the following command:
8+
9+
```bash
10+
curl -fsSL https://raw.githubusercontent.com/apiad/starter/main/install.sh | bash
11+
```
12+
13+
### 1. New Project (Scaffolding)
14+
Running `install.sh` in an empty directory will:
15+
- Initialize a fresh Git repository.
16+
- Extract the core `.gemini/` framework and configuration files.
17+
- Create the standard project structure (`journal/`, `plans/`, `research/`, `drafts/`).
18+
- Initialize baseline files (`README.md`, `CHANGELOG.md`, `TASKS.md`, `makefile`).
19+
- Perform an initial "feat" commit.
20+
21+
### 2. Existing Project (Integration)
22+
If run inside an existing project, the script will:
23+
- **Validate:** Ensure you have a clean Git working tree.
24+
- **Analyze:** Identify which framework files are missing or need updating.
25+
- **Confirm:** Present a summary of all proposed changes and wait for your approval.
26+
- **Integrate:** Add the `.gemini/` directory and core Markdown files without deleting your existing content.
27+
- **Commit:** Create a descriptive "feat" or "chore" commit with the changes.
28+
29+
## 🛠️ Prerequisites
30+
31+
To ensure full functionality, your environment should have:
32+
- **Git:** Required for state management and change detection hooks.
33+
- **Node.js:** Necessary for running the `gemini` CLI.
34+
- **Python 3.10+:** Required for executing the project's automation hooks (`.gemini/hooks/`).
35+
- **Make:** Used for project validation and health checks.
36+
37+
## 🚢 Getting Started
38+
39+
Once the installation is complete, follow these steps to orient yourself:
40+
41+
### 1. Run Onboarding
42+
Execute the `/onboard` command to get a high-signal overview of the repository's architecture, standards, and current roadmap.
43+
44+
```bash
45+
gemini /onboard
46+
```
47+
48+
### 2. Initialize the Roadmap
49+
Check the current `TASKS.md` file and use the `/task` command to define your project's initial goals.
50+
51+
### 3. Start a New Feature
52+
For your first feature, follow the standard workflow:
53+
- **Research:** `gemini /research [topic]`
54+
- **Plan:** `gemini /plan` (follow the interactive prompts)
55+
- **Implement:** Begin coding once the plan is saved in `plans/`.
56+
57+
---
58+
59+
*Next: See [Architecture & Systems](design.md) to understand how it works.*

‎docs/design.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Architecture & Systems
2+
3+
The **Gemini CLI Opinionated Framework** is not just a collection of scripts; it is an integrated system designed to empower AI agents while enforcing rigorous engineering standards.
4+
5+
## 🏗️ The Core Architecture
6+
7+
The project's "brain" resides in the `.gemini/` directory, which is organized into four primary systems:
8+
9+
### 1. The Hook System (`.gemini/hooks/`)
10+
Hooks are Python-based scripts that intercept the Gemini CLI turn lifecycle. They are the framework's primary enforcement mechanism.
11+
- **`session.py`:** Initializes the session and provides a project summary to the agent.
12+
- **`journal.py`:** Enforces the mandatory daily journaling requirement for all significant changes.
13+
- **`make.py`:** Automatically runs the `makefile` (tests/linting) to prevent regressions.
14+
- **`cron.py`:** Synchronizes the project's background tasks with systemd user timers.
15+
- **`utils.py`:** Provides a shared set of utilities for git status analysis and communication with the CLI.
16+
17+
### 2. The Command System (`.gemini/commands/`)
18+
Commands define structured, multi-phase workflows that automate the development lifecycle. Each command is a TOML file containing specific instructions and context for the agent.
19+
- **`/plan`:** An interactive workflow that transitions between clarification, analysis, and strategy generation.
20+
- **`/research`:** A deep-dive exploration that produces exhaustive reports in the `research/` directory.
21+
- **`/debug`:** Activates a forensic investigation mode for root-cause analysis.
22+
- **`/docs`:** Analyzes the codebase and project state to update the documentation suite.
23+
24+
### 3. Specialized Agents (`.gemini/agents/`)
25+
Instead of a single "do-it-all" AI, the framework delegates tasks to specialized sub-agents with restricted toolsets and focused personas (e.g., `planner`, `debugger`, `editor`, `reporter`). This ensures higher reliability and more consistent results.
26+
27+
### 4. State Management
28+
The framework maintains internal state to optimize operations and ensure continuity:
29+
- **`.gemini/last_make_run`**: Stores the timestamp of the last successful validation, allowing the framework to skip redundant tests.
30+
- **`.gemini/last_journal_update`**: Tracks when the journal was last updated to intelligently enforce the journaling requirement.
31+
- **`.gemini/settings.json`**: Configures the framework's global behavior and hook execution order.
32+
33+
## ⚙️ The Technology Stack
34+
35+
- **CLI Engine:** Gemini CLI (Interactive Node.js-based terminal).
36+
- **Core Automation:** Python (Hooks and specialized scripts).
37+
- **Validation & Health:** Make (Central source of truth for builds and tests).
38+
- **State & Versioning:** Git (Change detection and history tracking).
39+
- **Documentation:** Markdown (Universal format for journals, plans, and reports).
40+
41+
---
42+
43+
*Next: See [Development & Contribution](develop.md) for the rules of the road.*

‎docs/develop.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Development & Contribution
2+
3+
The **Gemini CLI Opinionated Framework** enforces a high-discipline development lifecycle. Whether you are a human or an AI contributor, adherence to these standards is mandatory.
4+
5+
## 🔄 The Mandatory Workflow Lifecycle
6+
7+
Every non-trivial change must follow this strict three-phase process:
8+
9+
### 1. Research & Analysis
10+
Before proposing a change, use the `/research` command to gather context, analyze the current codebase, and identify potential risks.
11+
12+
### 2. Strategic Planning
13+
A feature is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to generate this strategy and synchronize it with `TASKS.md`.
14+
15+
### 3. Execution & Validation
16+
- **Incremental Implementation:** Break features into small, testable commits.
17+
- **Continuous Validation:** After every implementation turn, the framework automatically runs the `makefile`. Do not attempt to bypass this process.
18+
- **Journaling:** A brief, one-line technical log must be added to the daily journal for every significant turn.
19+
20+
## ✅ Testing & Quality Standards
21+
22+
- **Source of Truth:** The `makefile` is the central definition of project health.
23+
- **Mandatory Commands:** Ensure `make test`, `make lint`, and `make format` pass before committing.
24+
- **Documentation-as-Code:** Any new feature must be accompanied by relevant updates to the `docs/` directory.
25+
26+
## 🌲 Git & Source Control
27+
28+
### 1. Clean Working Tree
29+
The framework requires a clean working tree for critical actions. Commit often to avoid merge conflicts or large, unmanageable diffs.
30+
31+
### 2. Conventional Commits
32+
All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) standard:
33+
- **`feat:`**: A new feature for the user.
34+
- **`fix:`**: A bug fix for the user.
35+
- **`docs:`**: Documentation-only changes.
36+
- **`chore:`**: Maintenance, dependencies, or internal tooling updates.
37+
- **`refactor:`**: Code changes that neither fix a bug nor add a feature.
38+
39+
### 3. Commit Scoping
40+
When possible, provide a scope to the commit message (e.g., `feat(onboard): add documentation discovery`).
41+
42+
## ✍️ Documentation Style
43+
44+
- **Markdown:** All documentation and logs must be in GitHub-flavored Markdown.
45+
- **Kebab-case:** Use kebab-case for all filenames in the `docs/`, `plans/`, and `research/` directories.
46+
- **Direct & Technical:** Documentation should be concise, high-signal, and technically rigorous.
47+
48+
---
49+
50+
*Return to the [Project Overview](index.md).*

‎docs/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Gemini CLI Opinionated Framework
2+
3+
Welcome to the **Gemini CLI Opinionated Framework**, a cognitive partnership model designed to transform how you work with AI agents.
4+
5+
This project is more than just a template; it is a structured environment that elevates the AI from a simple "code generator" or "copilot" to a **Senior Architect and Critical Thinking Partner**.
6+
7+
## 🧠 The Core Philosophy
8+
9+
The framework is built on the belief that AI is most effective when it is constrained by rigorous engineering standards and empowered by deep project context. We operate on three fundamental pillars:
10+
11+
### 1. Critical Cognitive Partnership
12+
The agent is mandated to challenge ideas before implementing them. It identifies technical flaws, security risks, or redundant logic, acting as a "peer reviewer" in real-time.
13+
14+
### 2. Strategy-First (Research -> Plan -> Execute)
15+
Every non-trivial change follows a strict, non-negotiable lifecycle. The agent first researches the domain, proposes a detailed implementation plan, obtains user approval, and only then begins writing code.
16+
17+
### 3. Validation-as-Truth
18+
The `makefile` is the ultimate source of truth for project health. Automated hooks ensure that every agent action is followed by a validation run (linting, testing, formatting) to prevent regressions.
19+
20+
## 🚀 Quick Start
21+
22+
The fastest way to bootstrap a new project or integrate the framework into an existing one is to run the following command in your terminal:
23+
24+
```bash
25+
curl -fsSL https://raw.githubusercontent.com/apiad/starter/main/install.sh | bash
26+
```
27+
28+
!!! success "Next Steps"
29+
After installation, run `gemini /onboard` to get an overview of the repository and start your first session.
30+
31+
## 🛠️ Key Capabilities
32+
33+
- **Deep Discovery:** Use `/research` for multi-phase domain investigations.
34+
- **Architectural Planning:** Use `/plan` to generate persistent, actionable strategies.
35+
- **Forensic Debugging:** Use `/debug` for root-cause analysis without immediate (and potentially incorrect) fixes.
36+
- **Automated Documentation:** Use `/docs` to keep the documentation synchronized with the evolving codebase.
37+
- **Roadmap Management:** Use `/task` to maintain a clear, version-controlled project roadmap in `TASKS.md`.
38+
39+
## 🔄 Project Lifecycle
40+
41+
1. **Onboarding:** Run `/onboard` to get a high-signal overview of the repository.
42+
2. **Scaffolding:** Use `/scaffold` to initialize new project components with modern tooling.
43+
3. **Iterative Development:** Follow the Research-Plan-Execute cycle for every feature.
44+
4. **Quality Control:** Rely on the `make.py` hook to maintain codebase integrity.
45+
5. **Releasing:** Use `/release` to automate versioning, changelog updates, and git tagging.
46+
47+
---
48+
49+
*Next: See [Deployment & Setup](deploy.md) to get started.*

0 commit comments

Comments
 (0)