Raven Architecture

Build with the user an understandable picture of the whole product's architecture: responsibilities of system parts, flows, where data is stored, integration boundaries and operational rules. The result is context/foundation/architecture.md, not an implementation, a list of libraries or a roadmap. Talk to the user in their language; write the document in the user's language unless the project already uses another.

Scope and permissions

The invocation authorizes reading sources and writing the document together with a short link in the relevant existing AGENTS.md (or CLAUDE.md when the project has no AGENTS.md). Do not change the PRD, code, service configuration, issues, Project statuses, other agent instructions or global preferences on the side. Do not commit, push, deploy or run the next skill without a separate request. Treat a foreign repo or one restricted by instructions according to where writing is allowed; do not install your own workflow there on your own.

Requirements and explicit user decisions are constraints, not suggestions to replace. Architecture describes facts and the agreed direction; it does not grant proposals the status of decisions. An existing stack is not an invitation to replace it. Do not introduce services, microservices, queues, caches, multi-tenancy or infrastructure for unagreed future needs.

1. Rebuild sources and the decision map

Distinguish a first draft, a resumed conversation and an update of a specific part. Read the existing architecture.md before writing anything. Keep untouched decisions, their IDs, justifications and sources.

Go through the repo's documentation inventory: instructions, README, the full current PRD/shape, stack/infrastructure documents, ADRs, security, testing, integration docs and lessons. Read all materials relevant to architecture; show missing sources and contradictions. Do not treat an archive as a current requirement. Do not read secrets or generated directories to fill in documentation.

Read the roadmap in GitHub Issues, only the needed changes/dependencies and local plans/research/decisions. Do not read the whole GH history and do not create a second queue. Name a source you cannot access while continuing with independent findings. Do not run setup on the side. A missing PRD in brownfield does not block the work if the goal and scope follow from other reliable materials; agree on genuinely missing requirements.

Check the areas of code and configuration relevant to decisions. Load available domain skills when analyzing their technology. Distinguish "exists and verified", "declared in documentation", "target, agreed" and "proposal". Writing "S3" in a document does not prove S3 is deployed.