Architecture Skill

Purpose

Produce a high-level architecture package that bridges PRD/story artifacts to designer-ready handoffs. Preserve traceability to FR/NFR and story IDs, avoid implementation detail, and surface uncertainty with targeted questions instead of guessing. Proactively ask clarifying questions whenever decisions affect scope, interfaces, or quality, and present up to 3 options with pros/cons so the user can choose.

Position in the Flow (Boundary)

This skill sits after PRD and User Story skills and before designer-specific technical specs. Do not pick frameworks, SDKs, database engines, or UI/UX details unless explicitly specified in input artifacts or optional context.

Inputs

Use artifacts from docs/ as authoritative inputs:

• •docs/prd.normalized.md
• •docs/prd.packet.json (authoritative FR/NFR IDs and handoff contract)
• •docs/story-map.json
• •docs/story-map.summary.md
• •optional_context (stack constraints, target platforms, existing systems)

If any required artifact is missing, ask targeted questions immediately and proceed with placeholders labeled TBD. When asking, include up to 3 possible approaches with pros/cons and ask the user to choose or clarify.

Outputs

Always write under docs/:

A) Architecture Brief (Markdown)

docs/architecture.brief.md with these headings:

1. •Overview & Goals
2. •System Context (actors + external systems)
3. •Component Boundaries
4. •Key Data Flows (mapped to epics/stories)
5. •Interface Map (API/event/UI boundary contracts)
6. •NFR Mapping (performance/security/reliability)
7. •Risks & Mitigations
8. •Assumptions & Open Questions
9. •Designer Handoff Summary

B) Architecture Packet (JSON) — Authoritative

docs/architecture.packet.json with stable structure and traceability:

• •meta: skill_name, version, generated_at, source_artifacts
• •components[]: id, purpose, responsibilities, dependencies
• •interfaces[]: type, direction, inputs/outputs, linked stories/FR/NFR
• •data_flows[]: source → target, trigger, linked story IDs
• •nfr_mapping[]: NFR ID → architectural response
• •traceability: story IDs ↔ FR/NFR IDs ↔ components
• •handoff_designers: frontend, backend, data, agentic
• •agentic_architecture: enabled, orchestration, agents, memory, tools, flows, frameworks
• •tbd.questions[], assumptions_made[], confidence[]

C) Designer Handoff Markdown (Derived)

Derived from architecture.packet.json (do not diverge):

• •docs/architecture.handoff.frontend.md
• •docs/architecture.handoff.backend.md
• •docs/architecture.handoff.data.md
• •docs/architecture.handoff.agentic.md (only if agentic_architecture.enabled = true)

Upstream Sync Expectations (Required)

The Architecture skill must keep upstream artifacts aligned by:

• •consuming docs/prd.packet.json and docs/story-map.json as authoritative for IDs and traceability,
• •pushing gaps or conflicts back into those artifacts when they affect flow integrity or requirement completeness.

Procedure

1. •Ingest artifacts from docs/. If missing, ask targeted questions and proceed with TBD placeholders.
2. •Preserve explicit lists verbatim (personas, epics, release slices, named constraints).
3. •Define system context: actors, external systems, boundaries.
4. •Partition components: UI/FE, API/backend, data layer, external services. Keep at architecture level.
5. •Map flows to components: for each key user flow, define data flows and interfaces.
6. •Map NFRs to architectural responses; do not assign implementation choices unless specified.
7. •Agentic architecture (if applicable):
   • •Set agentic_architecture.enabled to true only when inputs mention agents, orchestration, tools, or memory.
   • •Define roles, orchestration, memory boundaries, tool categories, and flow sequencing.
   • •Do not choose frameworks/SDKs unless explicitly provided; list as TBD otherwise.
8. •Emit outputs: JSON first (authoritative), then Markdown derived summaries.

Updating Upstream Artifacts (PRD / Story Map)

Update upstream artifacts only when required to preserve traceability:

• •If architecture uncovers missing requirements or acceptance criteria, update:
  • •docs/prd.packet.json → tbd.questions, tbd.missing_fields, or open_questions
• •If architecture introduces new story mapping needs (e.g., missing flow step), update:
  • •docs/story-map.json → ambiguities[] or unmapped_inputs[] Keep IDs stable and avoid paraphrasing user-provided lists.

End-to-End Flow Compatibility

This skill must remain compatible with the preceding PRD and User Story skills by ensuring:

• •source_artifacts in docs/architecture.packet.json references the exact PRD and story map files consumed,
• •traceability links stay intact (story IDs ↔ FR/NFR IDs ↔ components/interfaces),
• •any corrections are fed back upstream (PRD packet or story map) so the flow can be rerun deterministically.

Backend ↔ Agentic Handoff Sync

Ensure backend and agentic handoffs stay aligned:

1. •Shared boundary summary: include a short “shared responsibilities” section in both handoffs.
2. •Interface sync: list any API/event contracts that cross backend ↔ agentic boundaries in both handoffs.
3. •Change propagation: if an agentic change affects backend data flows or NFRs, update both handoff sections and the JSON traceability.
4. •Single source of truth: JSON is authoritative; Markdown handoffs are derived.

Failure Modes & Required Questions

• •Missing artifacts → ask for missing docs immediately.
• •Ambiguous flows → ask for entry points and expected system responses.
• •Conflicting IDs → preserve inputs and ask which ID is canonical.
• •Unclear NFR expectations → ask for measurable targets.
• •Unclear agentic scope → ask whether agents are in scope and their primary responsibilities. When any question has multiple plausible directions, propose up to 3 options with pros/cons to speed up user confirmation.