Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.skaro.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
PhaseWhat HappensOutput
ConstitutionDefine project-level principles (stack, standards, constraints)constitution.md
ArchitectureDescribe system design, get LLM review, define invariantsarchitecture.md, ADRs, invariants.md
ClarifyLLM asks questions to find gaps in your specclarifications.md
PlanLLM decomposes the task into stagesplan.md, tasks.md
ImplementLLM generates code stage by stageCode files + AI_NOTES.md per stage
TestsRun verification commands, generate testsTest results
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:
  1. Stack — language, framework, database, infrastructure (with specific versions)
  2. Coding Standards — linter, formatter, naming conventions
  3. Testing — minimum coverage, required test levels, framework
  4. Constraints — infrastructure, budget, compatibility limits
  5. Security — auth model, input validation, secrets storage
  6. LLM Rules — no stubs without justification, no duplication, always generate AI_NOTES
You can validate completeness with 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
All artifacts live in .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:
RolePhasesTypical Use
architectarchitecture, devplan, plan, import_analyzeStrategic decisions, planning
coderimplement, fixCode generation
reviewertests, clarifyValidation, question generation
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. 
# .skaro/config.yaml
skills:
  preset: react
  active:
    - our-api-conventions
  disabled:
    - react-testing
See Skills for the full reference and Custom Skills for creating your own.

​
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
Tasks are created either manually from the dashboard or automatically by the dev plan generator. Each task tracks its current phase and progress percentage. 
.skaro/milestones/
└── mvp/
    ├── user-auth/
    │   ├── spec.md
    │   ├── clarifications.md
    │   ├── plan.md
    │   └── stages/
    │       └── stage-01/
    │           └── AI_NOTES.md
    └── api-endpoints/
        └── ...

​
Definition of Done (DoD)

Each phase has explicit completion criteria. For example, the Clarify phase is done when the LLM has asked at least 5 questions, all answers are recorded, and no TODO/TBD markers remain in the spec. Skaro validates DoD through the CLI: 
skaro validate my-task-name
This checks phase-specific criteria and returns exit code 0 (pass) or 1 (fail), making it suitable for CI pipelines.