Skaro 2.0: artifacts for AI development

Skaro 2.0: Collaborative AI Development Environment Using Project Artifacts

Skaro 2.0 is a workspace where developers and AI tackle projects in clearly defined roles. Humans handle architecture, requirements, and key decisions. AI acts as the engineer: discussing tasks, writing code, and logging progress. At the core are artifacts—structured files in the repository that store architectural decisions (ADRs), plans, specs, and milestones. These serve as the project's external memory, preventing context loss.

Without artifacts, collaboration descends into chaos: decisions get forgotten, and AI generates code without referencing prior agreements. Skaro embeds chat directly into artifacts, keeping discussions right where they belong.

Directory Structure: .skaro

Artifacts form a hierarchical structure in the .skaro folder. Key components include:

.skaro
│   config.yaml
│   constitution.md
│   devplan.md
│   secrets.yaml
│   state.yaml
│   token_usage.yaml
│   usage_log.jsonl
│
├───architecture
│   │   adr-001-using-fastapi-as-web-framework.md
│   │   adr-002-simplified-layered-monolith-as-arch-pattern.md
│   │   architecture.md
│   │   chat-conversation.json
│   └───diagrams
├───milestones
│   └───01-foundation
│       └───config-module
│           │   clarifications.md
│           │   plan.md
│           │   spec.md
│           │   tasks.md
│           │   tests.json
│           └───stages
│               └───stage-01
│                   AI_NOTES.md
├───chat
│   tasks.json
└───templates
    adr-template.md
    plan-template.md

• architecture/: ADR files with decision rationales, diagrams.
• milestones/: Milestones with submodules, plans, tests, and AI notes.
• chat/: Task logs for context.
• templates/: Templates to standardize artifacts.

This structure lives in a Git repository, ensuring versioning and easy access.

Typical Workflow

Work kicks off with collaborative architecture docs alongside AI. Next, create devplan.md breaking things into milestones. Each milestone includes spec.md, plan.md, tasks.md, and stages with AI_NOTES.md.

• Discuss architecture in the architecture/ chat, lock in ADRs.
• Generate a milestone with subtasks.
• For each task, AI pulls initial context from artifacts and requests files.
• After implementation—auto-commit (optional).
• Update the task board on the home page.

Chat is fully contextual: embedded in artifacts and tasks, no context-switching needed.

Key Updates in Version 2.0

Skaro 2.0 streamlines the process:

• Contextual Chat: Available in architecture, milestones, tasks. Discussions saved as chat-conversation.json.
• Pre-Task LLM Context: Model reviews spec.md, plan.md, ADRs before starting.
• Auto-Commit: Configurable in config.yaml to commit changes post-task.
• Stats Dashboard: Dedicated page with token_usage.yaml and usage_log.jsonl.
• Kanban Board: Home page overview of milestones, stages, and tasks.
• UI Customization: Themes and accent colors for daily use.

Fixed stability and UI issues.

Roadmap

The open-source core remains: artifacts and collaborative model. Upcoming: team workspaces with access controls, token analytics, shared boards, and spend management.

Key Takeaways

• Artifacts as external memory: ADRs and milestones prevent context drift in AI dev.
• Role separation: Humans as architects, AI as implementers grounded in structure.
• Contextual chat: Discussions stay in the repo, not scattered windows.
• Automation: Pre-context and auto-commits reduce friction.
• Scalability: From solo dev to team workspace.

— Editorial Team