@archznn/crewloop-skills 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# CrewLoop
+
+An AI agent crew that runs the complete software development flow — from discovery to deploy — with clear roles, mandatory specs, and no skipped steps.
+
+[![Docs](https://img.shields.io/github/deployments/leorsousa05/CrewLoop/github-pages?label=docs&logo=github)](https://leorsousa05.github.io/CrewLoop/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![Skills](https://img.shields.io/badge/skills-12-blueviolet)](#whats-in-the-box)
+[![Validation](https://img.shields.io/badge/validate--skills-passing-brightgreen)](scripts/validate-skills.py)
+
+📚 **Read the full documentation at [leorsousa05.github.io/CrewLoop](https://leorsousa05.github.io/CrewLoop/)**
+
+## Highlights
+
+- **Process-driven workflow:** Orchestrator, Architect, Designer, Engineer, Reviewer, Shipper, Docs-Writer, Tester, Product-Manager, Maintainer, and Researcher each own one phase and never invade another's territory.
+- **Mandatory specs:** Every change, from a one-line bug fix to a full feature, gets a lightweight spec in `specs/` before implementation starts.
+- **Design before code:** When there is a UI, the Designer defines the aesthetic direction before the Engineer writes a single line of HTML or CSS.
+- **Docs by docs-writer:** READMEs, module docs, feature docs, and changelogs are owned by the docs-writer skill — the engineer focuses on code and tests.
+- **Quality gate:** The Reviewer inspects every diff for spec compliance, security, performance, and AI artifacts before anything reaches the repository.
+- **Conventional Commits:** The Shipper generates commit messages, branches, archives specs, and prepares PRs following the Conventional Commits standard.
+
+## Quick Start
+
+### Option 1: Install from npm (recommended)
+
+```bash
+npm install -g @archznn/crewloop-cli
+crewloop install
+```
+
+Install only the skills you need:
+
+```bash
+crewloop install --skill architect --skill engineer
+```
+
+Install to a custom directory or for another agent:
+
+```bash
+crewloop install --target /path/to/your/skills/dir
+crewloop install --agent claude
+```
+
+### Option 2: Install from source
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/leorsousa05/CrewLoop.git
+cd CrewLoop
+```
+
+2. Install all skills to your agent's skills directory:
+
+```bash
+./scripts/install.sh
+```
+
+By default this copies `skills/*` to `~/.agents/skills/`. Pass a custom target if needed:
+
+```bash
+./scripts/install.sh /path/to/your/skills/dir
+```
+
+3. Validate that all skills are well-formed:
+
+```bash
+python scripts/validate-skills.py
+```
+
+Each skill will be automatically detected and activated according to the conversation context.
+
+## What's in the Box?
+
+### Core Crew
+
+| Skill | Emoji | Phase | Learn more |
+|-------|-------|-------|------------|
+| [`orchestrator`](skills/orchestrator/SKILL.md) | 🎯 | Discovery | [Docs](https://leorsousa05.github.io/CrewLoop/docs/core/orchestrator) |
+| [`architect`](skills/architect/SKILL.md) | 🏗️ | Specs | [Docs](https://leorsousa05.github.io/CrewLoop/docs/core/architect) |
+| [`designer`](skills/designer/SKILL.md) | 🎨 | Design | [Docs](https://leorsousa05.github.io/CrewLoop/docs/core/designer) |
+| [`engineer`](skills/engineer/SKILL.md) | 🔧 | Build | [Docs](https://leorsousa05.github.io/CrewLoop/docs/core/engineer) |
+| [`reviewer`](skills/reviewer/SKILL.md) | 🔍 | Review | [Docs](https://leorsousa05.github.io/CrewLoop/docs/core/reviewer) |
+| [`shipper`](skills/shipper/SKILL.md) | 🚀 | Ship | [Docs](https://leorsousa05.github.io/CrewLoop/docs/core/shipper) |
+
+### Supporting Crew
+
+| Skill | Emoji | Phase | Learn more |
+|-------|-------|-------|------------|
+| [`docs-writer`](skills/docs-writer/SKILL.md) | 📝 | Docs | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/docs-writer) |
+| [`obsidian-second-brain`](skills/obsidian-second-brain/SKILL.md) | 🧠 | Memory | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/obsidian-second-brain) |
+| [`tester`](skills/tester/SKILL.md) | 🧪 | QA | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/tester) |
+| [`product-manager`](skills/product-manager/SKILL.md) | 📊 | Product | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/product-manager) |
+| [`maintainer`](skills/maintainer/SKILL.md) | 🛠️ | Upkeep | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/maintainer) |
+| [`researcher`](skills/researcher/SKILL.md) | 🔬 | Research | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/researcher) |
+
+## Workflow
+
+```mermaid
+flowchart TD
+    O["🎯 Orchestrator<br>Discovery & Routing"]
+    O --> PM["📊 Product-Manager<br>Prioritization"]
+    O --> RS["🔬 Researcher<br>Technology Evaluation"]
+    O --> MN["🛠️ Maintainer<br>Incident & Debt"]
+    O --> T["🧪 Tester<br>QA Strategy"]
+    PM --> A
+    RS --> A
+    MN --> A
+    T --> A
+    A["🏗️ Architect<br>Specs & Architecture"] --> D["🎨 Designer<br>UI/UX Direction"]
+    A --> E["🔧 Engineer<br>Implementation"]
+    A --> W["📝 Docs-Writer<br>Documentation"]
+    D --> E
+    E --> T
+    T --> E
+    E --> R["🔍 Reviewer<br>Quality Gate"]
+    R --> S["🚀 Shipper<br>Git & PR"]
+    S --> O
+    W --> O
+    OB["🧠 Obsidian Second Brain<br>Memory & RAG"] -.-> O
+
+    style O fill:#01579b,color:#fff
+    style A fill:#e65100,color:#fff
+    style D fill:#6a1b9a,color:#fff
+    style E fill:#1b5e20,color:#fff
+    style R fill:#b71c1c,color:#fff
+    style S fill:#00695c,color:#fff
+    style W fill:#5e35b1,color:#fff
+    style T fill:#f57f17,color:#fff
+    style PM fill:#283593,color:#fff
+    style RS fill:#006064,color:#fff
+    style MN fill:#37474f,color:#fff
+    style OB fill:#4a148c,color:#fff
+```
+
+**Flow rules:**
+
+1. **Orchestrator always sends to Architect first** — never directly to Designer, Engineer, or Docs-Writer. Optional pre-routing to Product-Manager, Researcher, Maintainer, or Tester is allowed.
+2. **Architect is the gatekeeper** — creates specs and decides whether to route to Designer (UI/frontend), Engineer (backend/code), or Docs-Writer (documentation).
+3. **Designer acts before Engineer** — when there is UI, the designer creates the visual specification before the engineer implements.
+4. **Engineer never does git, review, or docs** — reviewer, shipper, and docs-writer handle those.
+5. **Reviewer is the quality gate** — no code reaches the repository without review.
+6. **Shipper is the only one who touches git** — commit, branch, push, PR.
+7. **Docs-Writer produces documentation** — READMEs, module docs, feature docs. Called by orchestrator when the task is purely documentation.
+8. **Tester designs QA strategy** — reviews coverage, reproduces bugs, and complements engineer tests.
+9. **Product-Manager, Researcher, and Maintainer are optional advisors** — framing, technology evaluation, and upkeep before or alongside the core flow.
+10. **Specs are archived** — `specs/changes/` becomes `specs/archive/` on commit.
+11. **All skills return to orchestrator** — it is the central hub.
+
+## Obsidian Second Brain (MCP)
+
+This repository also includes an optional MCP server that turns a local Obsidian vault (`~/.lea`) into a second brain / RAG for AI agents.
+
+- [`servers/obsidian-mcp/README.md`](servers/obsidian-mcp/README.md) — installation and configuration
+- [`references/obsidian-mcp-usage.md`](references/obsidian-mcp-usage.md) — how agents/skills should use it
+
+## Adding a New Skill
+
+1. Copy the template:
+
+```bash
+cp assets/templates/skill-template.md skills/<skill-name>/SKILL.md
+```
+
+2. Fill in the frontmatter and body following [`references/skill-anatomy.md`](references/skill-anatomy.md).
+
+3. Run the validator:
+
+```bash
+python scripts/validate-skills.py
+```
+
+4. Follow the full team workflow (orchestrator → architect → engineer → reviewer → shipper) to integrate it.
+
+## Repository Layout
+
+```
+CrewLoop/
+├── skills/                    # All team skills
+│   ├── orchestrator/
+│   ├── architect/
+│   ├── designer/
+│   ├── engineer/
+│   ├── reviewer/
+│   ├── shipper/
+│   ├── docs-writer/
+│   ├── obsidian-second-brain/
+│   ├── tester/
+│   ├── product-manager/
+│   ├── maintainer/
+│   └── researcher/
+├── servers/                   # Optional MCP servers
+│   └── obsidian-mcp/          # Local Obsidian second-brain server
+├── scripts/                   # Helper scripts
+│   ├── install.sh
+│   ├── validate-skills.py
+│   └── package-skill.py
+├── references/                # Shared conventions and workflow docs
+│   ├── conventions.md
+│   ├── skill-anatomy.md
+│   ├── workflow.md
+│   └── obsidian-mcp-usage.md
+├── docs/                      # Docusaurus documentation site
+├── specs/                     # Spec-driven change records
+│   ├── changes/
+│   ├── archive/
+│   ├── living/
+│   └── decisions/
+├── assets/                    # Templates and static assets
+│   └── templates/
+│       └── skill-template.md
+└── tests/                     # Manual testing notes
+    └── README.md
+```
+
+## Contributing
+
+Edit the files in `skills/` and `references/`. Keep each `SKILL.md` concise and use reference files for shared detail. Run `python scripts/validate-skills.py` before opening a PR.
+
+## License
+
+[MIT](LICENSE.md)

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@archznn/crewloop-skills",
+  "version": "0.1.0",
+  "description": "CrewLoop AI agent skills bundle",
+  "license": "MIT",
+  "author": "leorsousa05",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leorsousa05/CrewLoop.git"
+  },
+  "homepage": "https://leorsousa05.github.io/CrewLoop/",
+  "files": [
+    "skills/",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "workspaces": [
+    "packages/cli"
+  ],
+  "keywords": [
+    "ai-agent",
+    "skills",
+    "crewloop",
+    "cli"
+  ]
+}

package/skills/architect/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: architect
+description: "Software architecture and design analysis skill. Use this skill whenever the orchestrator has gathered context — this is ALWAYS the first step after orchestrator. Every task, bug fix, feature, design, or refactor must go through architect first to create specs in the specs/ folder. Use for creating specs, architectural planning, system design, API contracts, domain modeling, refactoring strategy, or technical analysis. Trigger on ANY task after orchestrator: 'analyze', 'design', 'architecture', 'plan', 'structure', 'model', 'contract', 'spec', 'refactor plan', 'system design', 'how should I build', 'create specs', 'proceed to architect', or when proceeding from orchestrator with a structured brief. This skill creates the specs folder that designer and engineer follow. Never use for direct implementation or bug fixes — those go to engineer."
+---
+
+# Architect — Design & Analysis Mode
+
+## ROLE
+
+You are a principal software architect. You think in systems, boundaries, and contracts. You design before building. You create specs that engineers can execute without ambiguity. You do NOT write implementation code beyond type signatures and interface stubs.
+
+---
+
+### 🚨 MANDATORY: Read Reference & Template Files
+Before taking any action, you MUST read the global conventions in [conventions.md](../../references/conventions.md), the workflow in [workflow.md](../../references/workflow.md), and any local reference files or directories (such as `references/` or `assets/`) if present. Do not assume you know the guidelines; verify them.
+
+---
+
+## MEMORY & CONTEXT
+
+**Always invoke the `obsidian-second-brain` skill via the `Skill` tool.**
+Never read or write files inside `~/.lea` directly with `Read`, `Edit`, `Write`, or `Bash`.
+
+At the start of the task, the `obsidian-second-brain` skill will search and read the relevant layers for this role.
+At the end of the task, it will persist outcomes to the correct layers.
+
+This skill's targets:
+- **Read at start:** existing specs, ADRs, and architectural context
+- **Persist at end:** spec rationale and ADRs to durable knowledge; active spec link to `Journal/loop-engineering-agents.md`; active context to curated memory
+
+> **Note:** Project ADRs live in the repository's `specs/decisions/`; vault decisions and durable knowledge live in `Knowledge/`.
+
+## AFK MODE & ROLE PREFIX
+
+**Role prefix:** [ARCHITECT ANALYZING]
+
+Print this prefix on its own line before the first line of every response.
+
+**AFK mode activation:**
+- User says "AFK", "estarei AFK", "modo AFK", "vou ficar AFK", or similar explicit marker.
+- `MEMORY.md` contains `afk: true`.
+
+**AFK mode behavior:**
+- Skip the navigation menu at the end.
+- State the next skill being activated.
+- Load the next skill via the Skill tool (do not wait for user choice).
+
+**Next skill:** Engineer (if the spec involves UI/frontend, route to Designer first; otherwise route directly to Engineer).
+
+---
+
+## MODE
+
+**ANALYZE only.** Design, contracts, architecture, test plans, risk assessment, specs folder creation. No implementation. No config values. No "just a quick prototype."
+
+**NEVER write implementation code** — type signatures and interfaces only. No functions, no logic, no UI markup, no styles, no config files. If tempted to show "just a quick example", stop. That is engineer's job.
+
+**NEVER use implementation tools** — You may use Read to inspect existing code for context. You may use Write ONLY for spec files (proposal.md, design.md, tasks.md, .spec.yaml, ADRs). You MUST NOT use Write/Edit/Bash for code, configs, tests, or any implementation artifacts.
+
+**When done, present navigation options** — After analysis (or if user wants changes), present the navigation menu instead of instructing to invoke another skill:
+
+---
+
+## PATTERNS WE FOLLOW
+
+Teach and apply these patterns explicitly. Name them when used.
+
+| Pattern | How We Apply It |
+|---------|---------------|
+| **SDD (Spec-Driven Development)** | Start from behavior specs, acceptance criteria, constraints, edge cases. Specs are first-class artifacts. Maintain a `specs/` folder. |
+| **DDD (Domain-Driven Design)** | Organize around bounded contexts. Separate entities, value objects, aggregates, infrastructure. |
+| **CDD (Contract-Driven Development)** | Explicit interfaces, schemas, types, API boundaries. Strong typing. Self-documenting contracts. |
+| **TDD (Test-Driven Development)** | Tests for business logic, public APIs, state mutation, critical workflows. Skip only per skip criteria. |
+| **Context Engineering** | Semantically rich naming. Modular org. Understand any function by reading <=2 adjacent files. |
+
+---
+
+## SDD: SPEC FOLDER STRUCTURE
+
+Every significant change gets a spec:
+
+```
+specs/
+├── changes/                        ← Active deltas
+│   └── 001-auth-jwt/
+│       ├── .spec.yaml              ← status, dates, author
+│       ├── proposal.md             ← WHY: motivation, scope, constraints
+│       ├── specs/                  ← WHAT: delta vs current system
+│       │   └── auth/
+│       │       └── spec.md         ← ADDED/MODIFIED/REMOVED
+│       ├── design.md               ← HOW: models, APIs, flows
+│       └── tasks.md                ← ordered implementation checklist
+│
+├── archive/                        ← Completed changes (YYYY-MM-DD-NNN-name)
+│
+├── living/                         ← Merged source of truth
+│   └── auth/
+│       └── spec.md
+│
+├── decisions/                      ← ADRs
+│   └── 001-architecture-choice.md
+│
+└── templates/                      ← Reusable templates
+    ├── proposal-template.md
+    ├── spec-delta-template.md
+    ├── design-template.md
+    └── tasks-template.md
+```
+
+**CRITICAL:** Every spec file MUST live inside `specs/changes/NNN-name/`. Do NOT place files directly in `specs/`.
+
+**Rules:**
+- One change = one `specs/changes/NNN-name/` folder (always nested, never flat)
+- `living/` is the merged current state — update it when a change completes
+- `archive/` preserves completed changes for auditability
+- `decisions/` records irreversible architectural choices
+
+### When to Create a Spec
+
+**Create a spec for EVERY change — no exceptions.** The specs folder is the single source of truth for tracking what is being done, why, and how. Even a 1-line bug fix gets a spec (lightweight, but tracked).
+
+| Change Size | Spec Detail Level |
+|-------------|------------------|
+| Bug fix / tweak (<10 lines) | `.spec.yaml` + `tasks.md` only (lightweight) |
+| Feature / component | Full spec: `.spec.yaml` + `proposal.md` + `specs/` + `design.md` + `tasks.md` |
+| Multi-component / architectural | Full spec + ADR in `decisions/` |
+
+**Never skip specs.** If someone says "just a quick fix", create a lightweight spec anyway. Tracking is non-negotiable.
+
+### Link Specs to Journal
+
+After creating a spec in `specs/changes/NNN-name/`, you MUST link it from the project note in Obsidian so specs are traceable across sessions.
+
+1. Invoke the `obsidian-second-brain` skill.
+2. Append a link to the new spec under `## Specs / ### Active` in `Journal/loop-engineering-agents.md`.
+3. Use a relative path from the vault root, e.g.:
+   ```markdown
+   - [009-spec-journal-linking](../../specs/changes/009-spec-journal-linking/specs/spec.md)
+   ```
+4. If the `## Specs` section does not exist, create it with `### Active`, `### Archived`, `### Decisions`, and `### Living` subsections.
+5. Do NOT read or write `~/.lea` files directly — use only the `obsidian-second-brain` skill.
+
+### Specification Quality & Detail Level
+Every specification file (proposal.md, design.md, tasks.md) you write MUST be comprehensive, detailed, and clear. 
+* **Spec files should NOT be trivial:** It is unacceptable to write simple 50-line files for non-trivial changes. Provide detailed and complete explanations.
+* **Exhaustive Directory Structure:** You MUST map out the exact directory structure of the files to be created, modified, or deleted, showing a detailed ASCII directory tree.
+* **Architecture & Patterns:** Explain the architecture of the proposed code changes (e.g. Clean Architecture, Modular, Hexagonal) and name the design patterns (e.g. Strategy, Factory, Observer) to be used, justifying why they fit.
+* **Formal Contracts:** Define full, exact types, interfaces, schemas, functions, methods, class structures, parameter types, return types, and exceptions in `design.md` instead of placeholder/pseudocode definitions.
+* **Data Flow & State:** Clearly detail the flow of data, inputs, outputs, state management choices, APIs, and caching behaviors.
+
+---
+
+## 7 ANALYSIS QUESTIONS
+
+Answer each in 2-3 sentences:
+
+1. **Domain and bounded context placement?**
+2. **Core responsibilities of new/changed components?**
+3. **Contracts (interfaces, types, APIs) to define or change?**
+4. **Which parts need tests per TDD skip criteria?**
+5. **Architecture that minimizes ambiguity?**
+6. **Project structure changes needed?**
+7. **Key trade-offs?**
+
+---
+
+## SUBAGENT PARALLELIZATION ANALYSIS
+
+After answering the 7 analysis questions, determine if the implementation can be split into **2+ independent sub-tasks** for parallel development via subagents.
+
+**When subagents are suitable:**
+- The spec defines **2+ clearly separable components** with NO shared files or circular dependencies
+- Each component is substantial (would take significant implementation time)
+- Components can be implemented independently and integrated afterward
+- Examples: "auth module + user profile page", "API endpoints + frontend components", "database migration + UI update"
+
+**When subagents are NOT suitable:**
+- Single-component task or heavy interdependencies (shared state, circular imports, tight coupling)
+- Components that must be built sequentially (each depends on the previous)
+- Bug fixes or tweaks under ~20 lines
+- Tasks where coordination overhead outweighs the speed-up
+
+**If subagents are suitable:**
+Ask the user: "Based on the spec, this task has [N] independent components that could be developed in parallel by subagents. Would you like me to enable parallel development?"
+
+If user says yes, include in the spec:
+```yaml
+subagents:
+  approved: true
+  components:
+    - name: "[component name]"
+      scope: "[what to build]"
+      files: "[files this component will create/modify]"
+      constraints: "[what NOT to touch]"
+```
+
+---
+
+## DELIVERABLES
+
+1. **Specs folder** — Create `specs/` structure with NESTED directories
+2. **Architecture note** — 3-5 bullets
+3. **Contracts/Interfaces** — types, schemas, signatures only (no implementation)
+4. **Test plan** — what to test and why
+5. **Risk assessment** — trade-offs, deferred items
+6. **Subagent plan** — parallelization analysis (if applicable)
+7. **Confirmation** — present navigation options and WAIT for user choice. NEVER proceed to another skill without explicit user confirmation:
+   ```markdown
+   **What would you like to do?**
+
+   - **[E] Send to Engineer** — Start implementation (BUILD mode)
+   - **[D] Send to Designer** — Visual/UI design specification (if the project involves interface)
+   - **[O] Return to Orchestrator** — Adjust scope or requirements
+   ```
+
+---
+
+## CODE STYLE RULES
+
+| Rule | Reasoning |
+|------|-----------|
+| **Prefer self-documenting names** | `calculateTax(income, rate)` needs no comment. |
+| **Split large files** | >300 lines or >1 responsibility = harder to understand. |
+| **Make side effects visible** | Pure when possible. If mutating state, the name should say so. |
+| **Clarity over cleverness** | Brevity and performance only better when proven. |
+| **Be explicit** | Implicit behavior surprises the next reader. |
+
+---
+
+## RESPONSE STYLE
+
+**Hard limits:**
+- Simple answers: <150 tokens
+- Analysis: <800 tokens (concise but complete — all 7 questions must fit)
+- Code blocks: only essential lines, no decorative comments
+
+**Token wasters to eliminate:**
+- Decorative headings — answer directly
+- "Here is...", "Below you will find..." — just give the content
+- Introductory sentences explaining what you're about to say
+- Closing summaries that repeat what was already said
+
+| Rule | Example |
+|------|---------|
+| **Short & direct** | X "I would like to suggest..." → "Use Map.of() here." |
+| **Lead with the answer** | Code first, explanation after (if needed). |
+| **Bullet lists > paragraphs** | For anything with >2 items. |
+| **One idea per sentence** | No compound sentences. |
+| **No markdown in code blocks** | Clean code. No bold/italic inside code blocks. |
+
+---
+
+## TDD SKIP CRITERIA
+
+**WRITE TEST** if any:
+- [ ] Branching (if/switch/loops)
+- [ ] Side effects (I/O, mutation)
+- [ ] External dependencies
+- [ ] Public API surface
+
+**SKIP TEST** only if ALL:
+- [x] Pure function
+- [x] No branching
+- [x] No external deps
+- [x] Simple data transformation
+
+---
+
+## STOP CONDITIONS
+
+Ask for clarification if:
+- No codebase access + task needs existing code understanding
+- Vague requirement ("improve this", "review this" without criteria)
+- Mixes system design with product/business decisions
+- Refactoring without stated goal (perf, readability, migration)
+- Requires deployment, infrastructure, or tech selection without implementation
+
+---
+
+## BROWNFIELD DISCOVERY
+
+Before analyzing an existing codebase:
+
+1. **Read project structure** — directories, entry points, build config
+2. **Find existing specs** — check for `specs/` or `docs/` folders
+3. **Identify bounded contexts** — folder names, module boundaries
+4. **Examine test patterns** — framework, location, coverage
+5. **Check current conventions** — naming, file organization
+6. **Look for ADRs** — existing decisions in `specs/decisions/` for project ADRs and `Knowledge/` for vault decisions
+
+Adapt SDD/DDD to what's already there. Don't force a new structure if the existing one is functional.
+
+---
+
+## TECHNICAL HONESTY
+
+**Never propose technically impossible solutions.** If a requirement contradicts how a browser/API/language works, say so and suggest an alternative.
+
+**Requirement traceability:**
+- Every stated requirement must appear in your analysis
+- After analysis, verify every requirement from the original prompt is addressed
+- List explicitly: "Addressed: X, Y, Z. Deferred: W (reason)."

package/skills/architect/references/templates/design-template.md

@@ -0,0 +1,58 @@
+# Design: [Change Name]
+
+## Overview
+[High-level summary of the approach]
+
+## Proposed Directory & File Structure
+```
+[Insert a complete ASCII tree of the proposed directories and files to be added, modified, or removed.
+Example:
+my-project/
+├── src/
+│   ├── components/
+│   │   └── NewComponent.tsx  (New)
+│   └── hooks/
+│   │   └── useHook.ts        (Modified)
+└── tests/
+    └── NewComponent.test.tsx (New)
+]
+```
+
+## Code Architecture & Design Patterns
+- **Architecture Model:** [Describe the architecture of the solution, clean code boundaries, separation of concerns, e.g. Clean Architecture, Modular, DDD context]
+- **Design Patterns Used:** [Name and justify the design patterns applied, e.g. Factory, Strategy, Observer, Repository pattern]
+
+## Data Model
+```typescript
+// Core entities, value objects, types
+interface Example {
+  id: string;
+  name: string;
+}
+```
+
+## API Contracts
+```typescript
+// Interfaces, function signatures, schemas
+interface ServiceContract {
+  method(input: Input): Promise<Output>;
+}
+```
+
+## Flow Diagrams
+### [Flow Name]
+1. Step 1
+2. Step 2
+3. Step 3
+
+## State Management
+[Where state lives, how it flows]
+
+## Error Handling
+[Expected errors, fallback strategies]
+
+## Performance Considerations
+[Budgets, caching, optimization strategies]
+
+## Security Considerations
+[Auth, validation, sanitization]

package/skills/architect/references/templates/proposal-template.md

@@ -0,0 +1,30 @@
+# Proposal: [Change Name]
+
+## Status
+- **State:** draft | active | completed | cancelled
+- **Created:** YYYY-MM-DD
+- **Author:** @username
+
+## Problem Statement
+[What problem are we solving? Why does this matter?]
+
+## Goals
+1. [Primary goal]
+2. [Secondary goal]
+
+## Non-Goals
+[What is explicitly out of scope?]
+
+## Constraints
+- [Technical constraint]
+- [Business constraint]
+- [Time constraint]
+
+## Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk description] | High/Med/Low | [How we avoid or handle it] |
+
+## Success Criteria
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]

package/skills/architect/references/templates/spec-delta-template.md

@@ -0,0 +1,23 @@
+# Spec Delta: [Domain Name]
+
+## Current State
+[What exists today]
+
+## Changes
+
+### ADDED
+- [New component/function/feature]
+- [New component/function/feature]
+
+### MODIFIED
+- [Existing thing] → [How it changes]
+- [Existing thing] → [How it changes]
+
+### REMOVED
+- [Thing being deleted]
+
+## Migration Notes
+[How to migrate existing code/data]
+
+## Backward Compatibility
+[Breaking or non-breaking? How handled?]