# Reference Driven Development > Use when outside prior art reduces uncertainty: adapting a reference repo, porting a pattern, or when a relevant project-local reference// or reference/web// already exists and would materially help—even without an explicit use-this-reference request. - Skill: `ryan-brosas/reference-driven-development` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ryan-brosas/reference-driven-development` - Raw SKILL.md: https://api.skillmd.com/api/skills/ryan-brosas/reference-driven-development/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: ryan-brosas (https://skillmd.com/u/ryan-brosas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ryan-brosas/reference-driven-development --- # Reference-Driven Development ## Core Principle When outside code materially reduces uncertainty, start with ONE strong source, read its actual code and direct tests, compare boundaries, adopt/adapt/omit deliberately, and verify against the CURRENT project's gates. If a checkout helps, use `/reference//`; accessible source does not require a checkout or index. Never blind-copy; never mass-ingest. ## When to Use / NOT - **Use when:** adapting an external implementation; comparing against a reference repo; porting a known pattern; the user points at an upstream implementation to follow. - **Use when:** a relevant project-local code reference at `reference//` or web reference at `reference/web//` already exists and consulting it would materially reduce implementation uncertainty (even without an explicit "use this as inspiration" request). - **NOT when:** ordinary implementation where current project source, nearest implementation, and mechanical verification are enough; global `AGENTS.md` owns that default posture. This skill activates when outside prior art enters the loop. For an explicit discovery/admission request rather than using existing prior art, load `../inspo-qualify/SKILL.md`. It owns candidate qualification and approval. ## Workflow 1. **Ground locally**, inspect the current project and identify the seam; decide whether outside code materially reduces uncertainty (if not, stop, implement directly). 2. **Notice existing references**, if `reference/` or `reference/web/` exists, scan top-level names and open only candidates relevant to the seam (bounded listing, not bulk ingestion). 3. **Select the reference**, inspect accessible source directly when sufficient; acquire a checkout within authorized scope only when it materially helps, without overwriting an existing checkout. No indexing or setup execution is implied. When a checkout is useful, place or reuse it at the conventional path. Code references: ONE strong repository at `/reference//`; add a second only after naming the gap the first left. Web references: synthesis may combine several captured sites when each contributes a named quality. Full rules: `references/contract.md` (kinds, authority, defaults, licensing, lifecycle). 4. **Check freshness when it matters**, for a checkout reference, record the current revision and working-tree state; inspect configured upstream/remote when VCS and network capability exist; compare local revision to upstream metadata without mutating a dirty or diverged checkout. If freshness cannot be established, cite exact revision and mark freshness unknown or stale; do not treat unknown freshness as current. 5. **Read it as code, not docs**, use project-graph or semantic navigation MCP tools when helpful; read the exact source and its direct tests. 6. **Compare boundaries**, local vs reference; decide ADOPT / ADAPT / OMIT per concern; never blind-copy. 7. **Implement** in the current codebase; keep the reference untouched (read-only checkout). 8. **Verify against the CURRENT project's gates**, its tests/compiler/lint/CI, never the reference's own tests alone. Record provenance and license obligations in the PR's Reference/Prior-Art section. ## Reference sources A reference source is usually a repository, but the loop is the same for other evidence: - **Repository**: `reference//`; code and tests, acquired as a read-only clone. - **Website**: `reference/web//`; rendered visual and interaction evidence, captured by `web-reference`. This skill only consumes it. - **Design artifact**: an approved design state (for example an OpenDesign project); it becomes implementation evidence only after explicit approval. For a web reference, read `REFERENCE.md` first, then `manifest.json` for scope and coverage gaps. A partial capture is not complete knowledge. Site captures never become foundations (see the reference contract). ## Rules 1. **Examples beat specs**, 1–2 concrete examples from the reference one-shot what a spec takes pages to describe. 2. **The reference is prior art, not authority**, the current project's requirements and gates decide. 3. **One code reference at a time**; frontend synthesis may read several web references, each for a named quality. 4. **A reference repository is never converted** into a foundation skill, index, or corpus by default. 5. **Licensing obligations** are recorded when materially copying. ## Red Flags - Blind-copying reference code past the local boundary. - Turning the reference into an index/corpus/foundation by default. - Skipping local verification because the reference's tests passed. - Treating this skill as the default implementation posture, it is not. ## Verification - Relevant source was inspected; provenance + license recorded. A checkout path is required only when a checkout was used. Index/graph checks are not applicable to direct-source work. - The ADOPT/ADAPT/OMIT decision is stated per concern. - Changes verified against the current project's gates (named check + exit code). ## References - `references/contract.md`, canonical reference-checkout contract - `../push-pr/SKILL.md`, PR creation records the Reference/Prior-Art section