Initial README for CW-020 Gmail Inbox Architect

README.md

@@ -1,3 +1,58 @@
-# gmail-inbox-architect
+# Gmail Inbox Architect — CW-020
 
-CW-020 — Gmail Inbox Architect plugin: multi-skill system for building systematic Gmail classification pipelines. Claude is the architect; subcontractor agents handle token-heavy analysis via task orders.
+A multi-skill CoWork plugin that guides non-technical users through building a systematic
+Gmail classification pipeline. Claude acts as the permanent architect and quality gatekeeper
+across multiple sessions. Token-heavy inbox analysis is delegated to flat-rate or lower-cost
+agents (ChatGPT, Gemini, local LLMs) via structured task orders.
+
+## North Star Rules
+
+1. **Never brute-force the inbox.** Sample only. The survey builds the draft-one blueprint.
+2. **Bulk operations → lowest-cost path first.** Gmail UI, task order, or pre-built script before Claude tokens.
+3. **Non-technical user standard.** Plain English throughout. No assumed Gmail or API knowledge.
+4. **Claude is the architect.** Final decisions and all Gmail mutations stay with Claude.
+5. **No full inbox walk during survey.** Draft-one blueprint only — task orders dig the details.
+
+## Skills
+
+| Skill | Purpose |
+|---|---|
+| `survey` | Onboarding interview + label catalog + inbox sample. Creates Tracker, Bible.md, `_status.md`. |
+| `handoff` | Builds a complete task order (prompt + context MD + attachments) for a subcontractor agent. |
+| `import` | Parses batch work from external agents (MD/CSV/XLSX/JSON/XML). Sanity-checks and challenges. |
+| `deploy` | Implements approved rules: Gmail filters + Apps Script walkthroughs. |
+| `rule-review` | Interactive interview over `! Rule Needed` label. Designs rules using full toolbox. |
+
+## Project Artifacts
+
+Each user project creates its own Drive folder containing:
+- `Bible.md` — taxonomy, bylaws, decisions log, environment choice
+- `Tracker.xlsx` or `Tracker` (Google Sheet) — source of truth for all rules
+- `_status.md` — checkpoint file for inter-agent/inter-session handoff
+
+## Repo Structure
+
+```
+/skills/          — SKILL.md stub for each skill
+/references/      — Gmail_Filter_CoWork_Guide.md and methodology docs
+/examples/        — Sanitized sample artifacts showing expected formats
+```
+
+## Dependencies
+
+- Google Workspace MCP (Claude-side — for Gmail filter management and Drive operations)
+- Gitea optional (only if a Codex-style tool requiring a repo is involved)
+- No goldbrain dependency — continuity handled entirely via Drive artifacts
+
+## V2 Roadmap
+
+- `studio-flows` — Studio flow design assistant (deferred until design patterns are validated)
+- `health-check` — Periodic audit of rule health, label drift, DocScan accumulation
+
+## CW Registry
+
+- **ID:** CW-020
+- **Status:** Proposed
+- **Registry:** [Project Registry](https://docs.google.com/spreadsheets/d/1xN3l3CjhkpXQBo6hS85Qii86fC-yILg6qbxd33cChMA)
+- **Drive Folder:** [CW-020 — Gmail Inbox Architect](https://drive.google.com/drive/folders/1oXcHtf7UaBC3rBsVULeBBF2TIgSr8w7p)
+- **Concept Brief:** [CW-020_Concept.md](https://drive.google.com/file/d/1rdSNyscHldKnwII8jti17zPhavwe5KZA/view)