# Moonshot Architecture

> Convert a PRD or existing codebase objective into an evidence-grounded architecture design package before implementation planning.

- Skill: `munlucky/moonshot-architecture` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add munlucky/moonshot-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/munlucky/moonshot-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: munlucky (https://skillmd.com/u/munlucky)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/munlucky/moonshot-architecture

---


# Moonshot Architecture

## Use When

Use when a PRD or brownfield objective needs architecture decisions before planning.

## Route Away

Use `product-orchestrator` when intent is unresolved and `moonshot-plan-writer` after architecture acceptance.

## Role

Create an evidence-grounded design package between product definition and execution.

## Modes

- `greenfield_prd`: start from a PRD and produce architecture decisions before implementation planning.
- `brownfield_codebase`: recover the current architecture from repository evidence, then produce fit-gap and migration guidance.
- `hybrid_prd_plus_existing_repo`: combine PRD normalization with Brownfield constraints and produce `SPEC_DELTA`.
- `meta_harness_design`: design Moonshot Relay harness changes and hand them off to `moonshot-plan-writer`.

## Procedure

1. Classify the mode.
2. Build `projectKnowledgeContext` with the current stage and preserve status-only metadata.
3. Inspect project-local `knowledgeAnchors` declared in the target root `AGENTS.md`, if present. Select only anchors whose `mustConsultFor`/keywords match the current architecture scope, then read the smallest referenced agreement documents needed for evidence.
4. Build compact architecture context through `scripts/architecture-context-build.mjs` when available.
5. Normalize requirements into `REQUIREMENT_INVENTORY.md`.
6. Extract ASRs and quality attribute scenarios.
7. Build domain model, capability map, and data/integration flow.
8. For Brownfield/Hybrid work, recover current architecture and existing constraints from repository evidence.
8.1. Apply `docs/public/guidelines/retrieval-and-recency-policy.md` and `docs/public/guidelines/research-evidence-policy.md` when architecture inputs include current product, dependency, platform, model, pricing, legal, or security facts.
9. Generate at least two architecture options for non-trivial work.
10. Run trade-off review.
11. Write C4 model and ADRs for significant decisions.
12. Produce `SPEC.md` or `SPEC_DELTA.md`.
13. Produce `PLAN.md` and `TRACEABILITY_MATRIX.md`.
14. Run `architecture-gate-reviewer` and write `ARCHITECTURE_REVIEW.md`.
15. Hand off to `moonshot-plan-writer`, `moonshot-orchestrator`, or `moonshot-phase-runner` with explicit owned/read-only/staged paths and verification signals.

Internal stage-owner mapping is loaded conditionally from `references/architecture-flow.md`.

## Internal Stage Owners

Owners: `asr-extractor`, `architecture-option-generator`, `architecture-tradeoff-reviewer`, `adr-c4-writer`, `architecture-gate-reviewer`, and `codebase-architecture-recovery`. `architecture-gate-reviewer` supplies `ARCHITECTURE_REVIEW.md` readiness evidence; load the reference for artifact routing.

## Hard Stops

- Do not skip ASR extraction for non-trivial PRDs.
- In `greenfield_prd` mode, do not require Brownfield current-architecture evidence.
- Do not claim architecture readiness without ADRs for significant decisions.
- Do not produce a Greenfield implementation `PLAN.md` unless every accepted requirement maps to a quality scenario, ASR, ADR, task owner, and verification signal.
- Do not hand off to implementation without traceability from accepted requirements to owners and verification signals.
- Do not hand off to implementation without `architecture-gate-reviewer` readiness evidence.
- Do not invent Brownfield current architecture without repository evidence.
- Do not inline raw MemoryGraph records, KG edge dumps, ontology dumps, runtime logs, transcripts, browser scrapes, or secret-like strings.
- Do not mutate live `.claude/**`, `.codex/**`, account-root state, or runtime profiles during architecture design.
- Do not replace `moonshot-phase-runner` completion authority or `scripts/runtime-state.mjs assess-completion`.

## Output Contract

- Mode classification and input source path.
- Architecture package path.
- Project-local knowledge anchor disposition: consulted anchor IDs, consumed agreement paths, and skipped-anchor rationale when anchors were present.
- Retrieval/research evidence for current or volatile external facts, plus context relevance disposition for project knowledge anchors.
- Requirement inventory and ASR catalog.
- Domain/capability model or Brownfield current architecture evidence.
- Option comparison and trade-off review.
- ADR/C4 outputs for significant decisions.
- Architecture gate review status.
- Traceability matrix linking requirement IDs to implementation owners and verification signals.
- Handoff target and rationale.

## Public Surface Boundary

This is the public entrypoint; stage helpers stay internal. Executable `deepReferences` remain skill-local for package resolution.