initial commit

ai-tools/skills/architect/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: architect
+description: Create or update docs/architecture.md from user stories and project context.
+---
+
+# Architect
+
+Produce `docs/architecture.md`.
+
+## Process
+
+1. Read `docs/user_stories.md` and any existing `docs/architecture.md`.
+2. Produce or update `docs/architecture.md` using the template in `assets/template.md`.
+
+## Rules
+
+- Make reasonable assumptions and flag each with `[ASSUMPTION]`.
+- Ask only if a missing answer would materially change the architecture and cannot be inferred.
+- Keep the document as short as reasonably possible.
+- Mermaid diagrams only.
+- Be specific: version numbers, concrete patterns, no "best practices" filler.
+- If updating an existing document, preserve decisions that are still valid.

ai-tools/skills/architect/assets/template.md

@@ -0,0 +1,33 @@
+# Architecture: [Project Name]
+
+## Problem and context
+What problem this solves and for whom.
+
+## Goals and non-goals
+Numbered goals with measurable criteria. Explicit non-goals.
+
+## Repository structure
+Directory layout with one-line descriptions.
+
+## System overview
+One paragraph, then a Mermaid component diagram showing major components,
+responsibilities, and communication paths.
+
+## Technology stack
+| Component | Technology | Version | Rationale |
+
+## Module boundaries
+For each module: what it owns, its public interface, and what it must NOT do.
+Communication patterns between modules (sync/async, events, RPC).
+
+## Key architectural decisions
+For each important decision:
+- **Decision:** what was chosen
+- **Alternatives considered:** what else was evaluated
+- **Rationale:** why this option
+
+## Constraints and conventions
+Tech stack rules, naming conventions, forbidden libraries, project-wide patterns.
+
+## Open questions
+Only unresolved items that must be decided later.