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,

SKILL.md

GitHub

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/<module-name>.md. See 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-<slug>.md. Use the format in 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 <date> — 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: <now UTC>, resolved_by: <commit short sha or "manual">. 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: <ISO 8601 UTC with Z>, depends_on: [.forge/prd.md] — paths only, never hashes, generated_from: {.forge/prd.md: <upstream content_hash AT generation time>}, content_hash: <sha256 first 8 of THIS file's body>). 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.

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.