🤖 Gemini CLI Opinionated Framework

Transform how you work with AI agents.

A cognitive partnership model that enforces rigorous engineering standards, strategic planning, and continuous validation.

---

🧠 The Core Philosophy: AI as a Senior Partner

In this framework, the AI agent is not just a "code generator" or a "copilot". It is a Senior Architect and Critical Thinking Partner.

• 🛡️ Critical Feedback First: The agent is instructed to challenge unsafe, redundant, or poorly conceived ideas before writing a single line of code.
• 📋 Research -> Plan -> Execute: Every non-trivial change follows a strict lifecycle. The agent first researches context, proposes a detailed plan, waits for your explicit approval, and only then begins implementation.
• ✅ Validation-Always: The framework uses make as a source of truth. The agent is hooked into the makefile to ensure every change is validated (linted and tested) before being finalized.

---

🛠️ The Project Lifecycle

The .gemini/commands/ directory defines specialized workflows that automate every phase of the development lifecycle:

🔍 Phase 1: Planning & Discovery

• /research <topic>: A deep, 3-phase investigation (Planning -> Data Gathering -> Reporting) that produces exhaustive Markdown reports in the research/ directory. Crucial for gathering technical requirements and state-of-the-art context.
• /plan: The Architectural Bridge. This interactive workflow translates ideas into actionable execution plans:
  • Phase 1 (Clarification): The agent interviews you to resolve ambiguities before planning.
  • Phase 2 (Agentic Analysis): A specialized planner subagent scans the codebase and generates a detailed technical strategy.
  • Phase 3 (Artifact Generation): A persistent Markdown plan is saved in plans/ (e.g., plans/feature-x.md).
  • Phase 4 (Synchronization): The plan is optionally linked to TASKS.md and can be synchronized with GitHub issues.
• /onboard: Summarizes the project's architecture, standards, and current state to quickly orient a new developer (or the agent itself).

🏗️ Phase 2: Development & Execution

• /issues: Your gateway to GitHub integration. It allows you to list, create, or update issues. Use /issues work <number> to transition an issue directly into a detailed research and planning mode.
• /task: Manages the project roadmap in TASKS.md. Use it to create new tasks, work on existing ones (marks as In Progress), report on priorities, or update the roadmap.
• /scaffold: Initializes new project structures from scratch using modern, standard tooling (Python/uv, TS/npm, Rust/cargo, etc.) and sets up a compatible makefile.

🧹 Phase 3: Content Generation, Maintenance & Documentation

• /draft: Multi-phase workflow to turn research and plans into detailed, high-quality technical documents or articles section-by-section.
• /revise: Uses the editor subagent to perform structural and linguistic audits based on the project's style guide.
• /maintenance: Performs a deep scan of the codebase to identify technical debt, refactoring opportunities, and areas to improve test coverage.
• /docs: Analyzes the codebase and journals to generate or update comprehensive project documentation in the docs/ folder.
• /cron: Manages repetitive background tasks (e.g., health checks, automated reports) using systemd user timers.

🚀 Phase 4: Shipping & Quality

• /commit: Analyzes all uncommitted changes, groups them into logical features or fixes, and guides you through committing them individually using Conventional Commits.
• /release: Automates the final shipping steps: running tests, determining the next version (semver), updating the CHANGELOG.md, and tagging the release.

---

🔄 Standard Operating Procedures (SOPs)

This framework shines when you combine these commands into cohesive workflows:

1️⃣ Feature Development Workflow

1. Discover: Run /research to understand the domain or library.
2. Plan: Use /plan to turn requirements into a technical roadmap in plans/.
3. Track: Link the plan to TASKS.md using /plan's built-in sync.
4. Implement: Use /task work to mark progress and begin coding.
5. Refine: Run /docs to ensure your changes are well-documented.
6. Ship: Use /commit for clean history and /release for a new version tag.

2️⃣ Bug Resolution Workflow

1. Triage: Use /issues summary to see what needs attention.
2. Reproduce: Use /issues work <id> to research the root cause.
3. Fix: Develop the fix and validate with make.
4. Sync: Update the issue with the resolution details.

3️⃣ Content Creation Workflow

1. Research: Use /research to gather data into an executive report.
2. Draft: Run /draft to build an outline and expand it into a full article.
3. Revise: Use /revise for step-by-step style guide-driven audits and refinements.

---

⚓ The Hook System: Staying in Sync

The framework uses a robust hook system (.gemini/hooks/) that synchronizes the agent with your project state:

• session.py: Initializes the environment and provides a project summary.
• journal.py: Ensures a journal entry exists for the current date (journal/YYYY-MM-DD.md).
• make.py: Automatically runs make after critical agent actions to prevent regressions.
• cron.py: Synchronizes cron.toml tasks with systemd user timers.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.