# Architecture And Contracts > Use when .forge/prd.md exists and the system needs a structural design before task breakdown, when modules will be implemented in parallel and need interface contracts to prevent integration failures, or when non-obvious technical decisions need to be recorded for future reference. - Skill: `aneja5/architecture-and-contracts` (Agent Skill) - Install (CLI): `npx skillmds@latest add aneja5/architecture-and-contracts` - Raw SKILL.md: https://api.skillmd.com/api/skills/aneja5/architecture-and-contracts/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: aneja5 (https://skillmd.com/u/aneja5) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aneja5/architecture-and-contracts --- # Architecture and Contracts ## Overview Read `.forge/prd.md` and produce three artifacts: a system architecture document, precise interface contracts per module boundary, and ADRs for non-obvious decisions. Contracts must be specific enough that two engineers can implement different modules independently and integrate without surprises. ## When to Use - `.forge/prd.md` exists and is complete - System has 2+ modules that need to interact - Team will work in parallel — contracts prevent integration failures - Non-obvious tech decisions need to be recorded with rationale ## When NOT to Use - PRD doesn't exist yet — run `spec-driven-development` first - Trivial change touching only one module — skip straight to `tdd` - Architecture already exists and contracts are current — just update the affected contract ## Common Rationalizations | Thought | Reality | |---------|---------| | "We don't need contracts for a small feature" | Contracts protect parallel workers — without them, work diverges | | "I'll define interfaces as I implement" | Interfaces defined during implementation encode accidents as decisions | | "ADRs are bureaucratic overhead" | ADRs are the only record of why — without them, decisions get relitigated | | "The architecture is obvious from the PRD" | Make the obvious explicit — it's where disagreements hide | | "I can keep the architecture in my head" | You can. Your parallel workers can't. | ## Red Flags - Contracts written at function level instead of module boundary level - Input/output types described in prose instead of typed schemas - "Error handling: TBD" in any contract - Architecture document names files and line numbers (these rot) - ADR is missing a "Decision" section — only has "Context" - `.forge/contracts/` has no files after this skill runs ## Core Process ### Step 1: Read the PRD Read `.forge/prd.md`. Identify: module list, interaction points, data flows, NFRs that impose architectural constraints. ### Step 2: Explore existing architecture If a codebase exists, explore it. Understand current patterns, tech stack, existing module boundaries. The architecture must fit the existing system unless the PRD explicitly calls for a rewrite. ### Step 3: Design the system Produce a system overview: - Component diagram (text-based: boxes and arrows) - Tech stack decisions with rationale - Data flow for the primary user journey - Where each module from the PRD sits in the system ### Step 4: Write interface contracts For each module boundary identified in the PRD, write a contract file at `.forge/contracts/.md`. See [contract-templates.md](../../references/contract-templates.md). Each contract must define: - **Provides**: what this module exposes to callers - **Consumes**: what this module depends on - **Input types**: typed schemas for every input - **Output types**: typed schemas for every output - **Error types**: named error cases with conditions - **Invariants**: guarantees the module always maintains - **Not responsible for**: explicit out-of-scope list ### Step 5: Write ADRs For each non-obvious decision made in steps 3-4, write an ADR at `.forge/adr/NNN-.md`. Use the format in [contract-templates.md](../../references/contract-templates.md). **Required fields:** - `forge:meta` header with `last_reviewed_at` set equal to `generated_at` on creation. - Body header lines: `Status:` (Accepted on creation), `Superseded by:` (blank), `Supersedes:` (blank unless this ADR replaces a previous one). - Review log: one initial line ` — Created.` When this skill re-runs and the user identifies a decision that has been superseded: 1. Write the new ADR (`ADR-N+1`) with `Supersedes: ADR-N`. 2. Update the old ADR's body: `Status: Superseded by ADR-N+1`, `Superseded by: ADR-N+1`, bump `last_reviewed_at` to now-UTC, append a review-log line. ### Step 5b: Address pending feedback Before re-writing architecture or contracts on a re-run, read `.forge/feedback/*.md`. For every entry where `status: PENDING` AND `target_artifact` is one of this skill's outputs (`architecture.md`, `contracts/*.md`, `adr/*.md`): 1. Address the recommended change in the regenerated artifact. 2. Update the feedback entry in place: `status: RESOLVED`, `resolved_at: `, `resolved_by: `. Append a brief note describing what changed. If a feedback entry's recommendation is rejected (the team decides the current artifact is correct), mark it `status: DEFERRED` with a reason in the body. Do not delete feedback entries — they are historical record. ### Step 6: Cost modeling Include a cost model section in the architecture: - Per-unit cost breakdown (what does one transaction/request/user cost?) - Margin analysis per pricing tier (if applicable) - Cost scaling curve (how costs grow with 10x, 100x users) - Third-party API costs at projected volume ### Step 7: Write architecture.md Write `.forge/architecture.md` with system overview, component diagram, tech stack table, cost model section, and a table of all contracts with their module names and file paths. Prepend a `forge:meta` header (`generated_by: architecture-and-contracts`, `generated_at: `, `depends_on: [.forge/prd.md]` — paths only, never hashes, `generated_from: {.forge/prd.md: }`, `content_hash: `). Same header convention on every file under `.forge/contracts/` and `.forge/adr/` (co-output: each carries the same `depends_on` + `generated_from` set). See [forge-dependency-graph](../../references/forge-dependency-graph.md). ### Step 8: Expansion documents (optional) When the user requests deeper analysis, generate supplementary docs: - `docs/architecture/scalability-analysis.md` - `docs/architecture/microservices-design.md` - `docs/planning/testing-strategy.md` - `docs/planning/feature-priority-matrix.md` These are deeper dives on specific sections. Generate only when explicitly requested. ## Verification - [ ] `.forge/prd.md` read in full - [ ] On re-run: all PENDING feedback entries targeting architecture.md / contracts/ / adr/ addressed AND marked RESOLVED with `resolved_at` + `resolved_by` - [ ] Every module from the PRD has a contract in `.forge/contracts/` - [ ] Every contract has input types, output types, error types, and invariants - [ ] No contract says "TBD" in any required field - [ ] Architecture document uses component names, not file paths - [ ] At least one ADR written (even "use existing patterns" is a decision) - [ ] Every ADR has `last_reviewed_at` set on creation (== `generated_at`) - [ ] Superseded ADRs have `Status: Superseded by ADR-NNN` AND `Superseded by:` field filled - [ ] Cost model section included with per-unit costs and scaling curve - [ ] `.forge/architecture.md` written with component diagram - [ ] Contract table in architecture.md lists all contract files ## Fit-Check Before declaring done, emit one of: - A short list of specific fit issues observed (e.g., "Only 2 modules being changed but 6 contracts emitted — overscoped; consider skipping for single-module work next time" / "Cost model section assumed multi-tenant SaaS pricing; this is an internal admin tool with no cost dimension"). - The explicit line: **"No fit issues observed for this use case."** Silence is not allowed. See [docs/skill-anatomy.md#fit-check](../../docs/skill-anatomy.md#fit-check-the-meta-honesty-step).