Gemini CLI
Spec-driven AI development with betterspec and Gemini CLI.
Gemini CLI
betterspec integrates natively with Gemini CLI through betterspec init. No separate plugin or package is needed — the init command scaffolds all the necessary files directly into your project.
Setup
betterspec init
# Select your AI tool: Gemini CLIThis creates everything Gemini CLI needs to run a spec-driven workflow.
What betterspec init Creates
Agents in .gemini/agents/
Four specialized agent files are created:
| Agent | File | Role |
|---|---|---|
| Planner | .gemini/agents/planner.md | Reads the proposal. Writes requirements, scenarios, design, and tasks. Runs betterspec verify to confirm completeness. |
| Builder | .gemini/agents/builder.md | Reads the specs. Implements tasks one by one, checking them off as it goes. |
| Validator | .gemini/agents/validator.md | Reviews the implementation against requirements and scenarios. Runs tests, checks edge cases, reports issues. |
| Archivist | .gemini/agents/archivist.md | Archives the completed change, extracts knowledge, and updates capabilities. |
GEMINI.md Context
betterspec creates or updates a GEMINI.md file in your project root that tells Gemini CLI:
- Where specs are located
- How the betterspec workflow operates (propose → plan → build → validate → archive)
- That the builder should never validate its own work
- Where to find knowledge and capabilities
Skills
Skills are installed to .agents/skills/ or .gemini/skills/ depending on your skills location choice during init. Skills give Gemini CLI reusable workflows for common spec-driven tasks.
Workflow
A typical workflow with Gemini CLI and betterspec:
- Propose a change:
betterspec propose "Add rate limiting" - Use the Planner agent to flesh out specs
- Use the Builder agent to implement tasks
- Use the Validator agent to review the work
- If issues are found, the Builder fixes them
- The Archivist archives the change and extracts knowledge
The Golden Rule
The builder never validates its own work.
The Builder and Validator are separate agents with separate prompts. This separation catches mistakes that self-review misses — the same reason code review exists in human teams.