@archznn/crewloop-skills 0.2.0 → 0.3.0

package/README.md

@@ -4,14 +4,14 @@ An AI agent crew that runs the complete software development flow — from disco
 
 [![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)
+[![Skills](https://img.shields.io/badge/skills-14-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.
+- **Process-driven workflow:** Orchestrator, Architect, Designer, Engineer, Reviewer, Shipper, Docs-Writer, Tester, Product-Manager, Maintainer, Researcher, Security-Guard, and Accessibility-Auditor 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.
@@ -20,8 +20,6 @@ An AI agent crew that runs the complete software development flow — from disco
 
 ## Quick Start
 
-### Option 1: Install from npm (recommended)
-
 ```bash
 npm install -g @archznn/crewloop-cli
 crewloop install
@@ -40,28 +38,7 @@ 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:
+Validate that all skills are well-formed:
 
 ```bash
 python scripts/validate-skills.py
@@ -92,6 +69,8 @@ Each skill will be automatically detected and activated according to the convers
 | [`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) |
+| [`security-guard`](skills/security-guard/SKILL.md) | 🛡️ | Security Review | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/security-guard) |
+| [`accessibility-auditor`](skills/accessibility-auditor/SKILL.md) | ♿ | Accessibility Review | [Docs](https://leorsousa05.github.io/CrewLoop/docs/supporting/accessibility-auditor) |
 
 ## Workflow
 
@@ -117,6 +96,12 @@ flowchart TD
     S --> O
     W --> O
     OB["🧠 Obsidian Second Brain<br>Memory & RAG"] -.-> O
+    SG["🛡️ Security-Guard<br>Security Review"] -.-> R
+    AA["♿ Accessibility-Auditor<br>Accessibility Review"] -.-> R
+    R --> SG
+    R --> AA
+    SG --> E
+    AA --> E
 
     style O fill:#01579b,color:#fff
     style A fill:#e65100,color:#fff
@@ -130,6 +115,8 @@ flowchart TD
     style RS fill:#006064,color:#fff
     style MN fill:#37474f,color:#fff
     style OB fill:#4a148c,color:#fff
+    style SG fill:#b71c1c,color:#fff
+    style AA fill:#6a1b9a,color:#fff
 ```
 
 **Flow rules:**
@@ -143,8 +130,9 @@ flowchart TD
 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.
+10. **Security-Guard and Accessibility-Auditor are optional review specialists** — invoked by the Orchestrator or Reviewer when the change involves security-sensitive work or UI accessibility. They report findings back to the Engineer or Reviewer and do not touch git.
+11. **Specs are archived** — `specs/changes/` becomes `specs/archive/` on commit.
+12. **All skills return to orchestrator** — it is the central hub.
 
 ## Obsidian Second Brain (MCP)
 
@@ -187,13 +175,15 @@ CrewLoop/
 │   ├── tester/
 │   ├── product-manager/
 │   ├── maintainer/
-│   └── researcher/
+│   ├── researcher/
+│   ├── security-guard/
+│   └── accessibility-auditor/
 ├── servers/                   # Optional MCP servers
 │   └── obsidian-mcp/          # Local Obsidian second-brain server
 ├── scripts/                   # Helper scripts
-│   ├── install.sh
 │   ├── validate-skills.py
-│   └── package-skill.py
+│   ├── package-skill.py
+│   └── npm-publish-dry-run.sh
 ├── references/                # Shared conventions and workflow docs
 │   ├── conventions.md
 │   ├── skill-anatomy.md

package/assets/templates/skill-template.md

@@ -0,0 +1,58 @@
+---
+name: skill-name
+description: Describe what this skill does and when to use it. Be specific and include contexts where it should trigger even if the user does not explicitly name it. For example, mention related keywords, adjacent tasks, and competing skills where this one should win.
+---
+
+# Skill Name — One-Line Summary
+
+## ROLE
+
+Describe the role in 2-3 sentences. What is this skill responsible for? What does it NOT do?
+
+---
+
+## MODE
+
+**One-word mode.** What is the primary activity? (e.g., ANALYZE only, BUILD only, REVIEW only)
+
+**NEVER do X** — Explain the most important restriction.
+
+**NEVER do Y** — Explain another critical restriction.
+
+**When done, present navigation options** — After completing work, show the letter-based navigation menu.
+
+---
+
+## WORKFLOW
+
+### Step 1: Verify State
+
+What should the skill check first? Include example commands if useful.
+
+```bash
+# Example command
+git status --short
+```
+
+### Step 2: Do the Work
+
+Describe the core process step by step.
+
+### Step 3: Produce Output
+
+What deliverables or summary should the skill produce?
+
+---
+
+## RESPONSE RULES
+
+- Rule one
+- Rule two
+- Rule three
+
+---
+
+## ANTI-PATTERNS
+
+- ❌ Something this skill should never do
+- ❌ Another common mistake

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archznn/crewloop-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CrewLoop AI agent skills bundle",
   "license": "MIT",
   "author": "leorsousa05",
@@ -11,6 +11,9 @@
   "homepage": "https://leorsousa05.github.io/CrewLoop/",
   "files": [
     "skills/",
+    "references/",
+    "assets/",
+    "servers/obsidian-mcp/",
     "README.md",
     "LICENSE.md"
   ],

package/references/conventions.md

@@ -0,0 +1,144 @@
+# Team Conventions
+
+Shared conventions used by all Loop Engineering Agents skills.
+
+---
+
+## Conventional Commits
+
+All commits follow the [Conventional Commits](https://www.conventionalcommits.org/) standard.
+
+### Allowed types
+
+`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+### Description rules
+
+- Maximum 72 characters
+- Imperative mood: "add" not "added"
+- No trailing period
+- Lowercase after type/scope
+
+### Branch names
+
+Format: `<type>/<short-description>`
+
+- Max 50 characters for the description part
+- Kebab-case (hyphens, not underscores)
+- No uppercase letters
+
+---
+
+## Letter-Based Navigation
+
+At the end of each skill, present navigation options by letter:
+
+```markdown
+**What would you like to do?**
+
+- **[A] Architect** — Create or update specs
+- **[D] Designer** — Visual/UI design direction
+- **[E] Engineer** — Implement (BUILD mode)
+- **[R] Reviewer** — Code review and quality gate
+- **[S] Shipper** — Commit, branch, push, PR
+- **[O] Orchestrator** — New task or adjust scope
+```
+
+Use only the letters relevant to the current context.
+
+---
+
+## Spec Folder Structure
+
+```
+specs/
+├── changes/                        # Active deltas
+│   └── 001-change-name/
+│       ├── .spec.yaml              # status, dates, author
+│       ├── proposal.md             # WHY
+│       ├── specs/                  # WHAT
+│       ├── design.md               # HOW
+│       └── tasks.md                # ordered checklist
+├── archive/                        # Completed changes (YYYY-MM-DD-NNN-name)
+├── living/                         # Merged source of truth
+├── decisions/                      # ADRs
+└── templates/                      # Reusable templates
+```
+
+Rules:
+
+- Every spec lives inside `specs/changes/NNN-name/`. Never directly in `specs/`.
+- `living/` reflects the current state of the system.
+- `archive/` preserves completed changes for audit.
+- `decisions/` records irreversible architectural choices.
+
+---
+
+## Memory Conventions
+
+- Every skill invokes `obsidian-second-brain` via the `Skill` tool at task start and end.
+- Never read or write files inside `~/.lea` directly with `Read`, `Edit`, `Write`, or `Bash`.
+- Target the correct vault layer: `Knowledge/` for durable guides, `Journal/` for session outcomes, `Memory/` for user profile, `Notes/` for scratchpads, `_Inbox/` for proposals.
+- Full reference: `references/obsidian-mcp-usage.md`.
+
+---
+
+## Mandatory Workflow
+
+```
+Orchestrator → Architect → (Designer, if UI) → Engineer → Reviewer → Shipper → Orchestrator
+```
+
+Critical rules:
+
+- The orchestrator **always** sends to the architect first.
+- The architect creates specs for **any** change.
+- Designer acts **before** engineer when there is UI.
+- Engineer **never** executes git operations or reviews their own code.
+- Reviewer **never** writes code or runs git operations.
+- Shipper is the only one responsible for commit, branch, push, and PR.
+
+---
+
+## AFK Mode
+
+When the user explicitly activates AFK mode, skills route automatically through the workflow without presenting navigation menus.
+
+### Activation phrases
+
+Case-insensitive matches: `AFK`, `estarei AFK`, `modo AFK`, `vou ficar AFK`.
+
+When activated, set `afk: true` in `MEMORY.md` so subsequent skills know the mode is active. AFK mode resets when the workflow returns to Orchestrator after shipping, or when the user explicitly disables it.
+
+### Role prefixes
+
+Every skill response must start with its prefix on its own line:
+
+| Skill | Prefix |
+|-------|--------|
+| Orchestrator | `[ORCHESTRATOR TALKING]` |
+| Architect | `[ARCHITECT ANALYZING]` |
+| Designer | `[DESIGNER DESIGNING]` |
+| Engineer | `[ENGINEER BUILDING]` |
+| Reviewer | `[REVIEWER REVIEWING]` |
+| Shipper | `[SHIPPER SHIPPING]` |
+
+### Automatic routing
+
+When AFK mode is active, each skill proceeds to the next role in the standard workflow without waiting for user confirmation:
+
+```
+Orchestrator → Architect → (Designer, if UI) → Engineer → Reviewer → Shipper → Orchestrator
+```
+
+---
+
+## Patterns We Follow
+
+| Pattern | How We Apply It |
+|---------|---------------|
+| **SDD (Spec-Driven Development)** | Specs in `specs/` are the source of truth. |
+| **DDD (Domain-Driven Design)** | Organization by bounded contexts. |
+| **CDD (Contract-Driven Development)** | Contracts, interfaces, and explicit types. |
+| **TDD (Test-Driven Development)** | Tests before or alongside implementation. |
+| **Context Engineering** | Semantic names; understand function by reading ≤2 adjacent files. |

package/references/obsidian-mcp-usage.md

@@ -0,0 +1,190 @@
+# Obsidian MCP Second Brain — Usage for Agents
+
+This document explains how the Loop Engineering Agents team should use the local Obsidian MCP server (`servers/obsidian-mcp`).
+
+## What It Is
+
+A local MCP server exposes a vault at `~/.lea` as a second brain. The AI can:
+
+- Search existing knowledge (bundle + vault notes).
+- Read notes.
+- Create and update notes.
+- Learn from conversation text automatically via `learn_from_text`.
+
+## Vault Architecture
+
+The vault follows a **three-layer memory architecture**. Every skill in the bundle that reads from or writes to `~/.lea` must use these layers.
+
+```
+~/.lea/
+├── AGENT.md              # Entry point: read this first
+├── MEMORY.md             # Curated memory: read at session start
+├── memory/               # Working memory: raw session logs
+├── Memory/               # Durable user profile and preferences
+├── Knowledge/            # Long-lived technical guides and decisions
+├── Journal/              # Session logs and dashboards worth keeping
+├── Notes/                # Temporary notes, drafts, and research
+└── _Inbox/               # Agent proposals before promotion
+```
+
+### Layer Semantics
+
+| Layer | Path | When to Use |
+|-------|------|-------------|
+| Agent entry | `AGENT.md` | Read once per session before using the vault. |
+| Curated memory | `MEMORY.md` | Read at the start of every major task. Soft cap ~500 words. |
+| Working memory | `memory/` | Append raw, timestamped session logs. Pattern: `YYYY-MM-DD-HHMM.md`. |
+| User profile | `Memory/` | Durable facts about the user: role, preferences, goals. |
+| Knowledge | `Knowledge/` | Durable technical guides, architectural decisions, reusable docs. |
+| Journal | `Journal/` | Important session outcomes, project briefs, dashboards. |
+| Notes | `Notes/` | Temporary scratchpads, drafts, research not yet canonical. |
+| Inbox | `_Inbox/` | Proposed new canonical notes. Auto-promotion is allowed. |
+
+### Session Start
+
+1. Call `sync_from_bundle` once per session.
+2. Read `AGENT.md`.
+3. Read `MEMORY.md`.
+4. Search targeted layers based on the user's question.
+
+### Layer Selection Rules
+
+```
+User asks a question
+    ↓
+Read AGENT.md and MEMORY.md
+    ↓
+Durable concept or guide?       → search Knowledge/
+User preference or identity?    → search Memory/
+Recent session or decision?     → search Journal/
+Raw log of current conversation? → append to memory/
+Proposing new canonical knowledge? → create in _Inbox/
+```
+
+### Heartbeat / Distillation
+
+Every 2-4 sessions (or at the end of a significant task), the agent should:
+
+1. Read recent files in `memory/`.
+2. Update `MEMORY.md` with distilled, short-term-relevant facts.
+3. Promote durable facts from `_Inbox/` to `Memory/`, `Knowledge/`, `Journal/`, or `Notes/`.
+4. Archive or delete obsolete raw logs.
+
+Keep `MEMORY.md` under ~500 words. If it grows, move long-lived facts to `Knowledge/` or `Memory/` and keep only active context in `MEMORY.md`.
+
+## Frontmatter Rules
+
+The MCP server manages note frontmatter automatically. Callers should **not** include YAML frontmatter delimiters (`---`) inside `content`.
+
+### Server-managed fields
+
+| Field | Source | Behavior |
+|-------|--------|----------|
+| `title` | `title` parameter or derived from path | Always present; server value wins over any embedded value. |
+| `tags` | `tags` parameter plus any embedded tags | Union of caller tags and embedded tags, sorted, deduplicated. |
+| `created` | First save timestamp | Preserved across updates. |
+| `updated` | Current save timestamp | Refreshed on every save. |
+
+### Caller responsibilities
+
+- Pass `title` and `tags` as top-level parameters of `create_note` / `update_note`.
+- Keep `content` as the Markdown body only.
+- If `content` accidentally contains a frontmatter block, the server extracts it, merges the fields, and writes a single valid block.
+
+## Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `search_notes` | Find relevant notes. Prefer `mode: "hybrid"`. |
+| `read_note` | Read a specific note by path. |
+| `create_note` | Create a new note in the correct layer. |
+| `update_note` | Append or replace content. Use `append` to preserve history. |
+| `delete_note` | Remove a note. Use sparingly. |
+| `list_notes` | List notes, optionally filtered by folder. |
+| `get_related_notes` | Explore graph relationships from a note. |
+| `sync_from_bundle` | Re-index the skill bundle and local vault. |
+| `learn_from_text` | Detect concepts/decisions in text and auto-create notes. |
+
+## Note Paths
+
+Use English folder names and English note content:
+
+- `Memory/profile-user.md`
+- `Knowledge/obsidian-mcp-setup.md`
+- `Journal/2026-06-15-project-brief.md`
+- `Notes/2026-06-15-ml-concepts.md`
+- `_Inbox/proposed-knowledge-2026-06-15.md`
+
+## Privacy Rules
+
+Never persist in the vault:
+
+- API keys, secrets, tokens, passwords
+- Private keys or certificates
+- `.env` contents
+- Personal identifiable information (PII)
+
+The server has a privacy filter, but avoid sensitive input regardless. Review working memory before promoting anything to curated or structured layers.
+
+## Configuration Reminder
+
+The server must be installed and added to the agent's MCP config:
+
+```toml
+[mcpServers.obsidian-mcp]
+command = "/path/to/servers/obsidian-mcp/.venv/bin/python"
+args = ["-m", "obsidian_mcp.main"]
+```
+
+See `servers/obsidian-mcp/README.md` for full setup instructions.
+
+## Migration from Flat Folders
+
+Old flat folders (`concepts/`, `decisions/`, `projects/`, `dashboards/`) should be migrated to the new layers:
+
+- `concepts/` → `Knowledge/` (durable) or `Notes/` (transient)
+- `decisions/` → `Knowledge/`
+- `projects/` → `Journal/` (active) or `Knowledge/` (reference)
+- `dashboards/` → `Journal/`
+
+## Skill Memory & Context Pattern
+
+Every skill in the bundle must access the local Obsidian vault at `~/.lea` **only** through the `obsidian-second-brain` skill. Never read or write vault files directly with `Read`, `Edit`, `Write`, or `Bash`.
+
+### Before acting
+
+Invoke the `obsidian-second-brain` skill via the `Skill` tool. It will:
+
+1. Read `AGENT.md` once per session if not already loaded.
+2. Read `MEMORY.md` at the start of the task.
+3. Search the layers relevant to this skill's role (see table below).
+
+If the vault or MCP server is unavailable, continue without memory.
+
+### After acting
+
+Invoke the `obsidian-second-brain` skill again to persist outcomes to the correct layer:
+
+- Reusable guides, conventions, or architecture notes → `Knowledge/`
+- Session outcomes, decisions, or findings → `Journal/`
+- User profile facts or preferences → `Memory/`
+- Proposed canonical notes awaiting review → `_Inbox/`
+- Active context and priorities → update `MEMORY.md`
+
+## Per-Skill Memory Targets
+
+Each skill in the bundle should read from and write to the layers relevant to its role. See `skills/obsidian-second-brain/SKILL.md` for tool usage details.
+
+| Skill | Read at start | Persist at end |
+|-------|---------------|----------------|
+| `orchestrator` | `MEMORY.md`, `Memory/preferences.md` | User priorities/context to `MEMORY.md`; unclear items to `_Inbox/` |
+| `architect` | `Knowledge/`, `Memory/`, `Journal/decisions*` | Specs rationale to `Knowledge/`; ADRs to `Knowledge/` |
+| `designer` | `Memory/preferences.md`, `Journal/design*`, `Knowledge/brand*` | Design direction to `Journal/`; reusable systems to `Knowledge/` |
+| `engineer` | `Knowledge/`, `Journal/`, `Memory/` | Implementation notes to `Journal/`; reusable patterns to `Knowledge/` |
+| `reviewer` | `Knowledge/conventions*`, `Journal/decisions*`, `Memory/` | Review findings to `Journal/`; process updates to `Knowledge/` |
+| `shipper` | `Knowledge/conventions*`, `Memory/preferences.md` | Shipping log to `Journal/` |
+| `docs-writer` | `Knowledge/`, `Memory/preferences.md`, `Journal/` | New/updated docs to `Knowledge/` |
+| `researcher` | `Knowledge/`, `Journal/` | Research summaries to `Knowledge/` or `_Inbox/` |
+| `maintainer` | `Knowledge/`, `Journal/incidents*` | Incident/debt notes to `Journal/`; runbooks to `Knowledge/` |
+| `product-manager` | `Memory/preferences.md`, `Journal/`, `Knowledge/` | Decisions/metrics to `Knowledge/` or `Journal/` |
+| `tester` | `Knowledge/`, `Journal/bugs*` | Test strategies/heuristics to `Knowledge/` |

package/references/skill-anatomy.md

@@ -0,0 +1,77 @@
+# Skill Anatomy
+
+Guide for writing new skills in the Loop Engineering Agents project.
+
+---
+
+## File Structure
+
+```
+skills/<skill-name>/
+├── SKILL.md                 # Required. Instructions and frontmatter.
+└── references/              # Optional. Docs loaded into context as needed.
+    └── templates/           # Optional. Reusable templates.
+```
+
+For skills that need executable helpers, prefer scripts in the top-level `scripts/` folder rather than bundling them inside the skill.
+
+---
+
+## SKILL.md Frontmatter
+
+Every `SKILL.md` must start with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: When to trigger and what the skill does. Be specific and slightly pushy — include contexts where the skill should be used even if the user does not explicitly name it.
+---
+```
+
+### name
+
+- Must match the directory name
+- Lowercase, kebab-case
+
+### description
+
+- Primary triggering mechanism
+- Include what the skill does AND when to use it
+- Mention related keywords and adjacent contexts
+- 50-200 words is a good range
+
+---
+
+## SKILL.md Body
+
+Keep the body under 500 lines when possible. Use progressive disclosure:
+
+1. **ROLE** — What the skill is responsible for
+2. **MODE** — What it must and must never do
+3. **WORKFLOW** — Step-by-step process
+4. **RESPONSE RULES** — How to behave and respond
+5. **ANTI-PATTERNS** — Common mistakes to avoid
+
+### Tone
+
+- Use imperative form for instructions
+- Explain why things matter instead of heavy-handed MUSTs
+- Be specific in examples
+- Preserve letter-based navigation at the end
+
+---
+
+## Validation
+
+Run the validator after creating or editing a skill:
+
+```bash
+python scripts/validate-skills.py
+```
+
+This checks:
+- `SKILL.md` exists
+- Frontmatter is parseable
+- Required fields (`name`, `description`) are present
+- `name` matches the directory name
+- Description is not too short

package/references/workflow.md

@@ -0,0 +1,64 @@
+# Workflow Reference
+
+Complete workflow for the Loop Engineering Agents team.
+
+---
+
+## Team Roles
+
+| Role | File | Responsibility |
+|------|------|----------------|
+| Orchestrator | `skills/orchestrator/SKILL.md` | Context discovery and routing |
+| Architect | `skills/architect/SKILL.md` | Specs, contracts, architecture |
+| Designer | `skills/designer/SKILL.md` | Visual/UI direction |
+| Engineer | `skills/engineer/SKILL.md` | Implementation and tests |
+| Reviewer | `skills/reviewer/SKILL.md` | Code review and quality gate |
+| Shipper | `skills/shipper/SKILL.md` | Git operations and PR |
+| Security-Guard | `skills/security-guard/SKILL.md` | Deep-dive security review |
+| Accessibility-Auditor | `skills/accessibility-auditor/SKILL.md` | Accessibility and WCAG review |
+
+---
+
+## Flow Diagram
+
+```mermaid
+flowchart TD
+    O["🎯 Orchestrator<br>Discovery & Routing"] --> A["🏗️ Architect<br>Specs & Architecture"]
+    A --> D["🎨 Designer<br>UI/UX Direction"]
+    A --> E["🔧 Engineer<br>Implementation"]
+    D --> E
+    E --> R["🔍 Reviewer<br>Quality Gate"]
+    R --> S["🚀 Shipper<br>Git & PR"]
+    S --> O
+
+    SG["🛡️ Security-Guard<br>Security Review"] -.-> R
+    AA["♿ Accessibility-Auditor<br>Accessibility Review"] -.-> R
+    R -.-> SG
+    R -.-> AA
+    SG --> E
+    AA --> E
+
+    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 SG fill:#b71c1c,color:#fff
+    style AA fill:#6a1b9a,color:#fff
+```
+
+---
+
+## Routing Rules
+
+1. **Orchestrator ALWAYS sends to Architect first** — never directly to Designer or Engineer.
+2. **Architect is the gatekeeper** — creates specs and routes to Designer (UI) or Engineer (code).
+3. **Designer acts BEFORE Engineer** — visual spec before implementation.
+4. **Engineer never does git or review** — routes to Reviewer after BUILD.
+5. **Reviewer is the quality gate** — routes to Shipper if clean, or back to Engineer/Architect if issues are found.
+6. **Security-Guard and Accessibility-Auditor are optional review specialists** — invoked by the Orchestrator or Reviewer when the change involves security-sensitive work or UI accessibility. They report findings back to the Engineer or Reviewer and do not touch git.
+7. **Shipper is the only one who touches git** — commit, branch, push, PR.
+8. **All skills return to Orchestrator** — it is the central hub.
+
+Each skill reads from the second brain at the start of a task and persists outcomes at the end. The Orchestrator initiates memory reads during discovery; the Shipper updates `Journal/loop-engineering-agents.md` with active/archived spec links.