NOTES.md

skills/cowork-project-architect/NOTES.md

1. # Design Notes: cowork-project-architect
3. Notes on how this skill is built, for future maintainers and anyone iterating on it.
5. ## What this skill does
7. Turns a project idea into a complete Cowork project folder, structured as an Obsidian vault, through structured intake → architecture proposal → sign-off → generation.
9. ## Core design choices
11. **Intake before generation, always.** The single biggest failure mode for project scaffolding tools is generating a generic structure before understanding what the project is actually for. This skill enforces a sign-off step.
13. **Output is an Obsidian vault.** Numbered folders, frontmatter, wikilinks, MOC files, scoped subdirectory CLAUDE files. This makes generated projects work as proper vaults that can be navigated, graphed, and queried, rather than plain folders of markdown.
15. **Two MOCs, not one.** CLAUDE.md is the agent-facing MOC (custom instructions + reference index for Claude). 00-Index.md is the human-facing MOC (domain navigation, key concepts). Merging them confuses the audience.
17. **Subdirectory CLAUDE files are conditional and logged.** Only generate `CLAUDE-[scope].md` when the subdirectory has rules distinct from root. When generated, root CLAUDE.md must log them under "Subdirectory reference files." When not, root CLAUDE.md says "None. Root covers everything." This prevents future-you from wondering whether you missed something.
19. **File naming uses ALL CAPS for root Claude refs.** CLAUDE.md, MEMORY.md, etc. are visually distinct in the file explorer, easy to grep, matches Claude Code convention.
21. **Templates as separate files, not inlined.** Each deliverable has a `.tmpl` file in `templates/`. Easier to read, edit independently, version control as separate concerns.
23. **Bracket placeholders + HTML comment guidance.** Every template uses `[BRACKETS]` for fillable content and `<!-- ... -->` for instructions to Claude on how to fill them. The instructions get stripped from the final output.
25. **Heartbeat distinct from Memory distinct from Changelog.** Three different velocities of state:
26. - MEMORY.md = persistent, low-velocity, durable knowledge
27. - HEARTBEAT.md = ephemeral, high-velocity, save-state for in-flight work
28. - CHANGELOG.md = append-only historical record
30. **ADRs added beyond user spec.** DECISIONS.md pairs with CHANGELOG. Changelog records what changed; decisions records why. Both matter for retrieval.
32. **Sub-agents are conditional.** Most projects don't need them. The skill explicitly omits SUBAGENTS.md when it doesn't apply, rather than generating an empty placeholder.
34. **Skills inventory is a routing layer.** SKILLS_REFERENCE.md maps known skills to project triggers, and explicitly flags gaps where new skills should be built.
36. **RAG-friendly changelog.** Each entry is a self-contained chunk with consistent metadata so vector search retrieves the right one. No paraphrasing of old entries; append only.
38. **Wikilinks for in-vault references.** Survives renames, feeds graph view, makes Obsidian's backlinks pane useful. Markdown links only for external URLs and tools that don't render wikilinks.
40. **Frontmatter on every file.** Required: type, scope, created, updated. Optional: tags, aliases, status. Enables Dataview queries and tag-based search even if Dataview isn't installed.
42. ## Things deliberately not built (yet)
44. - **`.obsidian/` config pre-population.** Could ship sensible defaults (line numbers, file explorer state). Skipped for v1 because users have their own Obsidian preferences and overwriting them would feel intrusive. Obsidian creates `.obsidian/` on first open.
45. - **Examples folder.** Could include 1-2 completed projects as references for Claude. Skipped for v1; add when generation quality reveals weak spots.
46. - **Project structure visualizer.** Could render the folder layout as a diagram. Nice-to-have, not load-bearing.
47. - **Metrics file.** Originally considered METRICS.md for success criteria. Folded into README.md's "Success criteria" section to avoid file proliferation.
48. - **Prompts folder.** Could include reusable prompt templates per project. Most projects don't need this; can be added per-project as a knowledge subfolder.
49. - **Dataview queries in templates.** They only render if the plugin is installed. Skipped to keep templates plugin-agnostic. Add per-project on request.
51. ## Failure modes to watch for
53. 1. **Over-asking.** If the skill runs all five intake batches every time, it'll feel like a survey. The skill is told to read the room and skip questions already answered.
54. 2. **Generic CLAUDE.md.** If Claude pads the custom instructions with boilerplate, the project loses its specificity. Templates lean toward fewer-but-specific over comprehensive.
55. 3. **Sub-agent overgeneration.** Claude likes patterns; it'll want to add sub-agents to feel thorough. The skill explicitly says: only generate SUBAGENTS.md if the project actually uses them.
56. 4. **Subdirectory CLAUDE file overgeneration.** Same risk. Only when the subdirectory has rules distinct from root. Log every one in root CLAUDE.md or it disappears.
57. 5. **TBD markers ignored on delivery.** If the skill generates a project with [TBD] markers and doesn't surface them, the user might miss what needs filling. Phase 4 explicitly requires listing them.
58. 6. **Wikilink syntax errors.** Easy to fumble piped wikilinks in tables. The escape pattern `[[FILE\|display]]` matters.
59. 7. **Frontmatter date drift.** `created` and `updated` should both be today's date on generation. They diverge over time as files are edited.
61. ## Where to iterate
63. If this skill produces weak output, the most likely culprits in order:
64. 1. Templates too generic: tighten the per-project tailoring rules in SKILL.md.
65. 2. Intake too shallow: add more project-type-specific question banks in INTAKE_QUESTIONS.md.
66. 3. Generation order wrong: files reference each other; reorder if downstream files have stale info.
67. 4. Add an `examples/` folder with completed projects.
68. 5. Folder naming defaults don't fit the user's projects: adjust the convention in SKILL.md and OBSIDIAN_CONVENTIONS.md.
70. ## Skill maintenance
72. This is a meta-skill. When you build new project types and notice patterns the skill doesn't capture well, update INTAKE_QUESTIONS.md and the per-file generation rules in SKILL.md. When the Obsidian conventions evolve (new plugins worth supporting, new naming patterns), update OBSIDIAN_CONVENTIONS.md. Don't overload the templates. They should stay generic enough to fit any project type.