lemurOS:architecture

lemurOS:architecture

When to use

• <project>/docs/prd.md exists.
• <project>/docs/architecture.md does not exist, or the user has explicitly asked to revise an existing one.

When NOT to use

• No prd.md on disk — run lemurOS:prd first.
• The project already has a finalized architecture.md and the user has not asked to revise it.

Hard gates

Do NOT write `/docs/architecture.md` (or its vault mirror) directly. Always dispatch `lemurOS:write-architecture` — the Librarian is the sole writer. Iterate at least once with the user before dispatching. A first draft straight from the PRD is almost always wrong; the loop exists because the PRD captures requirements, not the architecture's exact shape. The body must cover all 14 sections enumerated below. Do not dispatch with a partial architecture — `lemurOS-task-structurer` depends on every section. Do not bump `meta.phase` directly. `lemurOS:write-architecture` is the operation that transitions `phase` from `architecture` to `tasks`.

Architecture shape

The architecture body mirrors docs/architecture.md. Compose the following 14 sections, each anchored to the canonical example:

1. System Overview — one-paragraph framing of the system; what it is, what it isn't, the top-level boundary.
2. Tech Stack — list framework, language, build system, persistence; pin versions only where required by deploy target. Split into frontend / backend / storage / infra sub-sections.
3. Folder Structure — annotated tree showing the top two or three levels; one line per directory describing its purpose.
4. Architecture Diagrams (Mermaid) — at minimum a component diagram and one happy-path sequence diagram. Use Mermaid fenced code blocks.
5. Database Schema — every table/collection with fields, types, and relations; or "no database" with a rationale grounded in the PRD's persistence needs.
6. API Design — every endpoint (or RPC, or IPC channel) with method, path, request shape, response shape, and error codes. Pressure-test against each user story in the PRD.
7. Authentication & Authorization — auth provider, session model, role/permission boundaries; or "no auth" with rationale.
8. Key Patterns & Conventions — module organization, dependency-injection style, error-handling, logging, naming conventions.
9. Project Initialization Checklist — ordered list of commands and files needed to bootstrap a fresh clone into a runnable state.
10. Infrastructure & Deployment — hosting target, CI/CD pipeline, environment promotion, secrets handling.
11. Testing Strategy — unit / integration / e2e split; tools per layer; coverage expectations.
12. Security Considerations — threat model bullets, secret handling, input validation, dependency hygiene.
13. Performance Considerations — expected load, hot paths, caching strategy, perf budgets.
14. Open Architecture Questions — unresolved decisions that need a follow-up before or during build.

Iteration loop

1. Compose a draft using prd.md plus the 14 sections above.
2. Show the draft to the user.
3. Collect feedback — sections to expand, choices to defend, decisions to revisit.
4. Revise.
5. Repeat steps 2-4 until the user says "ship it" (or equivalent explicit acceptance).
6. Once accepted, dispatch lemurOS:write-architecture with the full markdown body.

Handoff

Dispatch lemurOS:write-architecture via the Task tool with payload { content: <full markdown body of the architecture> }. On ok: true, emit READY_FOR_TASK_DETAIL.

What this skill must NEVER do

• Never write architecture.md directly — the Librarian is the sole writer.
• Never skip the iteration loop. "The first draft is the contract" is a smell that produces brittle architectures.
• Never bump meta.phase outside lemurOS:write-architecture.

Verdict

• READY_FOR_TASK_DETAIL — user accepted the architecture and lemurOS:write-architecture returned ok: true.
• NEEDS_CONTEXT — the PRD is missing a section you cannot defer; pause for user input.
• BLOCKED — Librarian rejected the write with IO_ERROR or repeated CONCURRENT_WRITE.