mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/meridian-skillsmainPrivate on GitHub, published here in full

SKILL.md

Markdown15.1 KB327 lines

skills/cowork-project-architect/SKILL.md

  1. ---
  2. name: cowork-project-architect
  3. description: >-
  4. Build a complete Claude project scaffold for Cowork, structured as an Obsidian vault, through
  5. interactive intake and architecture sign-off. Use whenever the user asks to "build a Claude
  6. project for X," "architect a Cowork project," "set up a project for X," "scaffold a new project,"
  7. "create a project for [task/domain]," "make me an Obsidian vault for [project]," or any variant
  8. where the goal is a complete, ready-to-drop-in project folder. Drives intake on purpose, mode,
  9. tasks, data, outputs, and constraints, then generates a tailored vault with CLAUDE.md custom
  10. instructions, MEMORY.md, HEARTBEAT.md, CHANGELOG.md, DECISIONS.md, model guide, sub-agent
  11. definitions, knowledge base, project MOC, and setup. Vault uses numbered folders, YAML
  12. frontmatter, wikilinks, and root-level Claude reference files that log pointers to any
  13. subdirectory-scoped CLAUDE files. Also runs a scope-shift path when an existing project has
  14. changed, updating affected files instead of regenerating.
  15. ---
  17. # Cowork Project Architect
  19. Purpose: turn a project idea into a working Cowork project folder, structured as an Obsidian vault. This skill is the orchestrator. Intake is conversational, output is a complete vault ready to point a Cowork project at and open in Obsidian.
  21. ## Operating principles
  23. 1. **Intake before output.** Never generate the project until the architecture is signed off.
  24. 2. **Tailor everything.** No generic boilerplate. Every deliverable reflects this specific project's purpose, cadence, and constraints. If a file doesn't apply, say so and skip it.
  25. 3. **Match existing patterns.** The user has established conventions in their MEMORY, personal preferences, organization instructions, and skill library. Honor them.
  26. 4. **Be opinionated.** Where the user is ambiguous, propose a default and explain the reasoning. Don't ask twenty questions.
  27. 5. **Mark explicit gaps.** If something genuinely cannot be filled, use `[TBD: description of what's needed]` markers. Don't fabricate.
  28. 6. **No emojis, no asterisk emotes** in any output. Generated projects are work artifacts; keep them clean.
  30. ## Obsidian vault conventions
  32. Every generated project is structured as an Obsidian vault. These conventions apply to all output files:
  34. ### Folder naming
  36. Numbered prefixes for ordered folders, underscore prefix for utility folders that should sort to the bottom:
  38. ```
  39. 00-Index.md (project MOC at root, sorts first)
  40. CLAUDE.md (always at root, no prefix)
  41. MEMORY.md (always at root, no prefix)
  42. [other root reference files]
  43. 01-Knowledge/ (primary domain content)
  44. 02-Working/ (in-progress files)
  45. 03-Outputs/ (finished deliverables)
  46. 04-Archive/ (optional, project-dependent)
  47. _attachments/ (images, PDFs, binaries)
  48. _templates/ (Obsidian note templates)
  49. .obsidian/ (Obsidian config, created on first open)
  50. ```
  52. Adjust folder names to match the project's actual content. A research project might have `01-Sources/`, `02-Notes/`, `03-Drafts/`. A code project might have `01-Specs/`, `02-Code/`, `03-Reviews/`. The numbered-prefix pattern stays consistent.
  54. ### File naming
  56. - **Root Claude reference files**: ALL CAPS with .md extension. CLAUDE.md, MEMORY.md, HEARTBEAT.md, CHANGELOG.md, DECISIONS.md, MODEL_GUIDE.md, SUBAGENTS.md, SETUP.md, SKILLS_REFERENCE.md, README.md.
  57. - **Subdirectory Claude reference files**: `CLAUDE-[scope].md` pattern. E.g., `01-Knowledge/CLAUDE-knowledge.md`. The CLAUDE prefix preserves grep/search visibility and the scope suffix names the directory it governs.
  58. - **Other notes**: kebab-case for general notes (`client-onboarding.md`), Title-Case for canonical references (`Project-Charter.md`), or whatever the user's existing vaults use.
  60. ### YAML frontmatter
  62. Every generated `.md` file starts with frontmatter. Standard fields:
  64. ```yaml
  65. ---
  66. type: [claude-instructions | project-memory | working-state | changelog | decisions | model-guide | subagents | setup | skills-reference | readme | moc | knowledge-index | etc.]
  67. scope: [project-root | 01-Knowledge | 02-Working | etc.]
  68. tags:
  69. - claude
  70. - [other relevant tags]
  71. created: [YYYY-MM-DD]
  72. updated: [YYYY-MM-DD]
  73. aliases:
  74. - [optional alternate names for Obsidian search]
  75. ---
  76. ```
  78. Frontmatter enables Dataview queries, tag-based filtering, and Obsidian search. Keep it consistent across templates.
  80. ### Wikilinks
  82. Internal references between files use wikilinks (`[[FILENAME]]`), not Markdown links. Wikilinks make Obsidian's graph view useful and survive file renames. Examples:
  84. - `[[MEMORY]]` not `[MEMORY](MEMORY.md)`
  85. - `[[01-Knowledge/CLAUDE-knowledge|knowledge-scoped instructions]]` for piped display text
  86. - `[[CHANGELOG#2025-05-07]]` for section-anchored links
  88. External links and tool-rendered links (where Obsidian isn't the renderer) stay as standard Markdown.
  90. ### Maps of Content
  92. Two MOCs by design:
  94. 1. **CLAUDE.md**: agent/Claude-facing MOC. Custom instructions body PLUS an index of all Claude reference files in the vault, including subdirectory `CLAUDE-[scope].md` files.
  95. 2. **00-Index.md**: human/domain-facing MOC. Project navigation, key concepts, links into 01-Knowledge.
  97. These do different jobs and should not be merged.
  99. ### Subdirectory CLAUDE files
  101. Subdirectories MAY have their own `CLAUDE-[scope].md` file when:
  102. - The subdirectory has operational rules distinct from the root
  103. - Granular instructions would clutter root CLAUDE.md
  104. - A specific data type or workflow lives in that folder and warrants its own context
  106. When a subdirectory CLAUDE file exists, root CLAUDE.md MUST log it under the "Subdirectory reference files" section with:
  107. - Wikilink to the file
  108. - One-line description of its scope
  109. - When to read it
  111. If no subdirectory CLAUDE files exist, the section in root CLAUDE.md says so explicitly: "No subdirectory-scoped Claude reference files in this vault." This prevents future-you from wondering whether you missed any.
  113. ## Phase 1: Intake
  115. Open with one line, no preamble:
  117. > "Let me build this out. I'll batch the questions so this doesn't feel like a survey."
  119. Then ask in this order, batching 2-4 questions per message based on what's already been said. Skip questions the user has already answered in their initial request.
  121. ### Batch 1: Frame
  122. - What's the project's job, in one sentence?
  123. - Who uses it? (Just you, you + collaborators, client-facing)
  124. - Is it interactive (you chat with Claude), agentic (Claude works autonomously on long tasks), or hybrid?
  126. ### Batch 2: Surface area
  127. - What kinds of tasks will Claude handle? (Research, writing, coding, data, design, comms, analysis)
  128. - What data lives in the project? (Files, CSVs, scraped content, notes, prior outputs)
  129. - What does Claude produce? (Drafts, code, structured data, decisions, briefs)
  131. ### Batch 3: Constraints
  132. - Cadence: daily, weekly, project-bounded, on-demand?
  133. - Sensitivity: privacy, copyright, confidentiality, identifiable persons?
  134. - Existing skills, templates, or prior projects this should plug into?
  136. ### Batch 4: Vault structure (only if non-default)
  137. - Any folder organization that should match an existing vault you have?
  138. - Are there subdirectories that need their own scoped CLAUDE files (e.g., a clients/ folder with per-client rules)?
  139. - Tag taxonomy you want me to seed, or build it as we go?
  141. ### Batch 5: Only if relevant
  142. - Tool / MCP integrations (Gmail, Drive, Calendar, Todoist, custom MCP)?
  143. - Quality bar: rough draft and iterate, or production-ready first pass?
  144. - Anything to deliberately exclude from scope?
  146. Do not run all five batches if the first two settle it. Read the room.
  148. ## Phase 2: Synthesis
  150. After intake, write a one-screen architecture proposal in this exact shape:
  152. ```
  153. Project: [name]
  154. Purpose: [one sentence]
  155. Mode: [interactive / agentic / hybrid]
  156. Cadence: [daily / weekly / on-demand / project-bounded]
  158. Vault structure:
  159. [project-name]/
  160. ├── 00-Index.md
  161. ├── CLAUDE.md
  162. ├── MEMORY.md
  163. ├── [other root reference files]
  164. ├── 01-[Folder]/ ([purpose])
  165. ├── 02-[Folder]/ ([purpose])
  166. └── _templates/, _attachments/
  168. Subdirectory CLAUDE files: [list, or "None. Root CLAUDE.md covers everything."]
  170. Primary tasks:
  171. - [task]
  173. Knowledge base seeds:
  174. - [file/folder, with one-line description]
  176. Sub-agents (if any):
  177. - [name]: [one-line role]
  179. Models:
  180. - Default: [Opus / Sonnet / Haiku]
  181. - Heavy reasoning: [model]
  182. - High-volume: [model]
  184. Skills to surface:
  185. - [skill name]: [why it applies]
  187. Tag taxonomy:
  188. - [seed tags for the vault]
  190. Files to generate: [list]
  191. Files to skip: [with one-line reason]
  193. Open questions / TBDs:
  194. - [item]
  195. ```
  197. End with: "Sign off and I'll generate the vault, or push back on anything."
  199. Wait for explicit sign-off before generating. If the user pushes back, revise and ask again.
  201. ## Phase 3: Generation
  203. Generate the vault using the templates in `templates/`. Each template has placeholder markers in `[BRACKETS]`, frontmatter to populate, and HTML comment guidance (`<!-- ... -->`) that should be removed in the final output.
  205. ### Standard vault structure
  207. ```
  208. [project-name]/
  209. ├── 00-Index.md (project MOC, domain navigation)
  210. ├── CLAUDE.md (custom instructions + Claude-file MOC)
  211. ├── MEMORY.md
  212. ├── HEARTBEAT.md
  213. ├── CHANGELOG.md
  214. ├── DECISIONS.md
  215. ├── MODEL_GUIDE.md
  216. ├── SUBAGENTS.md (omit if no sub-agents)
  217. ├── SETUP.md
  218. ├── SKILLS_REFERENCE.md
  219. ├── README.md
  220. ├── 01-Knowledge/
  221. │ ├── KNOWLEDGE_INDEX.md
  222. │ ├── CLAUDE-knowledge.md (only if subdirectory rules differ from root)
  223. │ └── [domain knowledge files or placeholders]
  224. ├── 02-Working/
  225. │ └── .gitkeep
  226. ├── 03-Outputs/
  227. │ └── .gitkeep
  228. ├── _attachments/
  229. │ └── .gitkeep
  230. └── _templates/
  231. └── note-template.md (sample note template using project frontmatter)
  232. ```
  234. Adjust folder names per project. Numbered prefix pattern stays. Naming: kebab-case lowercase, no spaces. If the user gave a project name, normalize it.
  236. ### Per-file generation rules
  238. **00-Index.md**: Project Map of Content. Domain navigation for humans. Lists key concepts, points into 01-Knowledge, surfaces frequently-used files. Distinct from CLAUDE.md. Template: `templates/00-Index.md.tmpl`.
  240. **CLAUDE.md**: The most important file. Custom instructions body + index of all Claude reference files (root and subdirectory). This is what gets pasted into Cowork's project settings. Spend tokens here. Template: `templates/CLAUDE.md.tmpl`.
  242. **MEMORY.md**: Persistent, low-velocity project context. Read at session start. Not a session log. Template: `templates/MEMORY.md.tmpl`.
  244. **HEARTBEAT.md**: Ephemeral working state. Save state for in-flight work. For interactive-only projects, keep minimal but still create. Template: `templates/HEARTBEAT.md.tmpl`.
  246. **CHANGELOG.md**: RAG-friendly change log. Self-contained chunks. Template: `templates/CHANGELOG.md.tmpl`.
  248. **DECISIONS.md**: ADRs. Pairs with CHANGELOG (what changed) by recording why. Template: `templates/DECISIONS.md.tmpl`.
  250. **MODEL_GUIDE.md**: Task-to-model mapping. Tailor to actual project tasks. Template: `templates/MODEL_GUIDE.md.tmpl`.
  252. **SUBAGENTS.md**: Only generate if the project actually uses sub-agents. Omit entirely otherwise. Template: `templates/SUBAGENTS.md.tmpl`.
  254. **SETUP.md**: Five to eight numbered steps. Includes Cowork setup AND opening the vault in Obsidian. Template: `templates/SETUP.md.tmpl`.
  256. **SKILLS_REFERENCE.md**: Skills relevant to this project, with trigger phrases. Flag gaps. Template: `templates/SKILLS_REFERENCE.md.tmpl`.
  258. **README.md**: Cold-open project overview. Template: `templates/README.md.tmpl`.
  260. **01-Knowledge/KNOWLEDGE_INDEX.md**: Routing layer for the knowledge folder. Template: `templates/knowledge/KNOWLEDGE_INDEX.md.tmpl`.
  262. **Subdirectory CLAUDE-[scope].md files**: Only generate when the project actually warrants scoped instructions. Template: `templates/CLAUDE-scope.md.tmpl`. Every one generated MUST be logged in root CLAUDE.md under "Subdirectory reference files."
  264. **_templates/note-template.md**: A starter note template using the project's frontmatter convention. Helps the user create new notes with consistent metadata.
  266. ### Generation order
  268. 1. README.md (anchors the rest)
  269. 2. CLAUDE.md (most decisions get made here, including the subdirectory file index; generate a placeholder index and fill it in at step 13)
  270. 3. MEMORY.md
  271. 4. MODEL_GUIDE.md
  272. 5. SUBAGENTS.md (if applicable)
  273. 6. SKILLS_REFERENCE.md
  274. 7. KNOWLEDGE_INDEX.md
  275. 8. Any subdirectory `CLAUDE-[scope].md` files
  276. 9. HEARTBEAT.md
  277. 10. CHANGELOG.md (with one initial entry: "Project initialized")
  278. 11. DECISIONS.md (with one initial entry: the architecture choices made during synthesis)
  279. 12. 00-Index.md (last because it links to everything else)
  280. 13. SETUP.md
  281. 14. **Final pass**: revisit CLAUDE.md and populate the "Subdirectory reference files" section with wikilinks to every `CLAUDE-[scope].md` actually generated.
  283. ### Wikilink and frontmatter discipline during generation
  285. - All file-to-file references inside the vault use wikilinks (`[[FILENAME]]`).
  286. - Every generated `.md` file has a populated YAML frontmatter block at the top.
  287. - `created` and `updated` dates are today's date.
  288. - Tags should be specific to the project, not just generic ("claude", "memory"). Also tag with the project domain ("research", "outreach", "design", etc.) to make cross-project graph view useful.
  290. ## Phase 4: Delivery
  292. Bundle the vault into a single zip and present it. Tight summary:
  293. - Project name and one-line purpose
  294. - Three files to look at first (usually CLAUDE.md, MEMORY.md, MODEL_GUIDE.md)
  295. - Any `[TBD]` markers that need user input
  296. - Suggested first-run task to validate setup
  297. - One line on how to open in Obsidian: "Open Obsidian → Open folder as vault → point at `[project-name]/`"
  299. End the response there. Don't pad.
  301. ## Scope-shift path
  303. If the user says an existing project's scope has shifted, do not regenerate from scratch:
  305. 1. Ask the user to share the current CLAUDE.md, MEMORY.md, and CHANGELOG.md (or read them).
  306. 2. Re-interview only on the dimensions that changed.
  307. 3. Update only the affected files.
  308. 4. Append a CHANGELOG entry documenting the shift.
  309. 5. Append a DECISIONS entry if the change reflects a real architectural choice.
  310. 6. Update MEMORY.md only if the change is durable.
  311. 7. If a subdirectory CLAUDE file is added or removed, update root CLAUDE.md's subdirectory index.
  312. 8. Deliver the updated files plus a diff summary.
  314. ## Anti-patterns
  316. - Don't ask all questions at once.
  317. - Don't generate before sign-off.
  318. - Don't fabricate domain detail. Use `[TBD]` markers.
  319. - Don't include templates the project doesn't need.
  320. - Don't paraphrase the user's existing MEMORY or custom instructions into the new project. Copy verbatim or link.
  321. - Don't pad MODEL_GUIDE.md with all four models if the project only uses two.
  322. - Don't include emojis or asterisk emotes anywhere in output.
  323. - Don't generate sub-agents for the sake of having sub-agents.
  324. - Don't generate subdirectory CLAUDE files speculatively. Only when the project demonstrably needs them.
  325. - Don't merge CLAUDE.md and 00-Index.md. They serve different audiences.
  326. - Don't use Markdown links for in-vault file references. Use wikilinks.
  327. - Don't skip frontmatter to save lines. It's load-bearing for Obsidian search and Dataview.