The .skaro/ Directory
Every Skaro project has a .skaro/ directory at the root. This is where all artifacts live — constitution, architecture, task specs, plans, and AI notes. The directory is version-controlled with Git, so your entire project context is reproducible and shareable.
The key idea: context comes from files, not from chat history. When Skaro calls the LLM, it passes the relevant files from .skaro/ as context. This means you can start a new chat session, switch to a different LLM, or hand off to a teammate — nothing is lost.
See .skaro/ Directory for the full file map.
Phases
Every task in Skaro goes through a sequence of phases. Each phase has defined inputs, outputs, and a Definition of Done:
Constitution and Architecture are set up once per project. Clarify → Plan → Implement → Tests is the per-task pipeline.
There is also a Project Review that runs separately — it cross-validates the entire codebase against the spec, architecture, and constitution. This is not part of the task pipeline but is triggered from a dedicated dashboard section.
Phases are sequential — you cannot skip Clarify and jump to Implement. Each phase builds on the output of the previous one.
Constitution
The constitution is a Markdown file (.skaro/constitution.md) that defines the immutable principles of your project. Every LLM call references the constitution to maintain consistency across phases.
A valid constitution must include six sections:
- Stack — language, framework, database, infrastructure (with specific versions)
- Coding Standards — linter, formatter, naming conventions
- Testing — minimum coverage, required test levels, framework
- Constraints — infrastructure, budget, compatibility limits
- Security — auth model, input validation, secrets storage
- LLM Rules — no stubs without justification, no duplication, always generate AI_NOTES
skaro constitution validate. Skaro also ships 12 presets for popular frameworks (React, FastAPI, Django, etc.) to help you get started. Each preset automatically activates a matching set of Skills — LLM instruction packs with framework-specific patterns.
Artifacts
Artifacts are the Markdown files that Skaro generates and manages throughout the development process. They are the single source of truth for your project:- Project-level: constitution, architecture, invariants, ADRs, dev plan
- Task-level: spec, clarifications, plan, task decomposition, AI notes per stage
.skaro/ and follow a consistent template-based structure. When a phase runs, it reads the relevant artifacts as input and writes new ones as output.
Roles
Skaro divides LLM work into three roles, each covering specific phases:
Each role can use a different LLM provider and model. For example, you might use Claude for architecture decisions, Groq for fast code generation, and a local Ollama model for reviews. If a role is not configured, it falls back to the default LLM settings.
See Role-Based Routing for configuration details.
Skills
Skills are YAML-based instruction packs that teach the LLM framework-specific patterns beyond what the constitution covers. While the constitution defines what your project uses (stack, standards), skills define how the LLM should write code for that stack. Skaro ships 28 bundled skills covering all 12 constitution presets. When you select a preset (e.g., React), the matching skills are activated automatically. You can also enable any skill individually from the full catalog, or create custom skills for your team’s conventions. Skills are filtered by phase and role — a React component skill won’t appear during the Tests phase, and a testing skill won’t appear for the Architect role.Milestones & Tasks
Work in Skaro is organized into milestones and tasks:- A milestone is a group of related tasks (e.g., “MVP”, “Authentication”, “API v2”)
- A task is a single unit of work that goes through all phases independently