Agent-Skills.md

Agent Skills: Moonshot Architecture

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

UncategorizedID: munlucky/claude-settings/moonshot-architecture

Repository

munlucky/claude-settings
munlucky

Install this agent skill to your local

pnpm dlx add-skill https://github.com/munlucky/moonshot-relay/tree/HEAD/skills/moonshot-architecture

Skill Files

Browse the full folder contents for moonshot-architecture.

Download Skill

Loading file tree…

skills/moonshot-architecture/SKILL.md

Skill Metadata

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

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.