A robust, AI-native framework for high-velocity software engineering, prioritizing technical clarity and execution excellence.
This repository defines the core methodology, agents, and specialized skills that power a Spec-Driven Development workflow. By separating "what" from "how," and "how" from "implementation," we ensure that every line of code serves a verified purpose.
The framework follows a strict, sequential pipeline to minimize rework and maximize code quality:
graph LR
A[Spec] --> B[Review]
B --> C[Design]
C --> D[Review]
D --> E[Tasks]
E --> F[Build]
F --> G[Validate]
- Spec Phase: Define requirements. (See spec driven development.md and example-spec.txt)
- Review Phase: Rigorous validation of the Spec or Design.
- Design Phase: Technical architecture. (See example-designmd.txt)
- Tasks Phase: Granular task breakdown. (See creating-tasks.txt)
- Build Phase: The actual coding phase, where features are implemented following the task list.
- Validate Phase: Ensuring the implementation meets all acceptance criteria.
The framework utilizes a fleet of specialized subagents, each optimized for a specific phase of the SDD lifecycle:
| Agent | Role | Definition File |
|---|---|---|
| Spec Specialist | Feature Definition | spec.md |
| Architect (Design) | Technical Design | design.md |
| Task Decomposer | Planning | create-tasks.md |
| Code Reviewer | Quality Control | code-reviewer.md |
| UI Designer | Visual Excellence | ui-designer.md |
| Tech Expert | Deep Research | tech-expert.md |
| TypeScript Pro | Implementation | typescript-pro.md |
| README Generator | Documentation | readme-generator.md |
| Search Specialist | Discovery | search-specialist.md |
Skills are bundled instruction sets and resources that extend agent capabilities:
fallow: Static analysis for dead code and complexity management.vercel-react-best-practices: Performance optimization for Next.js/React.write-a-skill: The meta-skill for creating new capabilities.
We maintain a multi-layered context system to ensure AI agents operate with consistent rules and philosophies:
- Global Context: AGENTS_MD/global/GEMINI.md - System-wide rules for languages and standards.
- Project Context: AGENTS_MD/project/GEMINI.md - Repository-specific guidelines and philosophies.
- Knowledge Items (KIs): Curated, localized knowledge about the repository to avoid redundant research and adhere to established patterns.
Integrated into the design phase are premium aesthetic guidelines (tailored for shadcn/ui and Tailwind v4) defined in DESIGN_GUIDELINES.md:
- Typography: Strictly 4 font sizes and 2 weights (Regular/Semibold) for maximum clarity.
- Grid System: A rigorous 8pt grid (all spacing divisible by 8 or 4).
- Color Distribution: The 60/30/10 rule (60% neutral, 30% complementary, 10% accent).
- Aesthetics: Vibrant colors, glassmorphism, and modern typography (Inter, Outfit).
- Initialize: Pull latest from
main, create a feature branch. - Spec: Use the Spec Specialist agent (or
/speccommand) to define requirements. - Review: Ask the AI to review the spec against edge cases.
- Design: Use the Architect agent to create
design.md. - Tasks: Use the Task Decomposer to generate a phased
tasks.mdwith To-Dos. - Build: Hand off tasks to implementation agents in chunks.
- Validate: Verify against the original acceptance criteria.
- Ship: Commit, Push, PR, Merge, and Delete branch.
.
├── AGENTS_MD/ # Global and Project-level AI context/rules
├── Fire Your Design Team/ # Premium UI/UX design guidelines
├── GEMINI CLI sub agents/ # Specialized agent instructions (markdown)
├── skills/ # Core skill definitions and resources
├── spec driven development.md # Detailed methodology documentation
└── ... # Example specs, designs, and task lists
This framework is designed for developers who want to move faster while building higher-quality, more maintainable software.