Source-Driven Development Approach: A Framework Decision Methodology for Production Code

Source-driven development is a disciplined four-step workflow that grounds every framework decision in official, version-matched documentation to ensure accuracy, traceability, and future-proof code.

The source-driven development approach is defined in the addyosmani/agent-skills repository as a systematic alternative to memory-based or tutorial-driven coding. Instead of relying on Stack Overflow snippets or recopied boilerplate, this methodology binds every implementation choice to authoritative sources, creating an auditable trail from dependency version to documentation page to implemented code.

The Detect → Fetch → Implement → Cite Cycle

According to the canonical definition in skills/source-driven-development/SKILL.md【L27-L36】, source-driven development operates on a strict four-phase cycle. Each phase produces artifacts that justify the resulting code.

Detect Stack and Versions

The workflow begins by parsing dependency manifests to surface exact framework versions. In skills/source-driven-development/SKILL.md【L38-L49】, the approach mandates reading package.json, pyproject.toml, go.mod, or equivalent files before writing any implementation code.

// Detect versions from package.json (pseudo‑code)
import fs from 'fs';
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf‑8'));

const reactVersion = pkg.dependencies?.react ?? pkg.devDependencies?.react;
console.log(`Detected React version: ${reactVersion}`);

This step prevents version drift, ensuring that subsequent documentation lookups target the correct API surface for the installed library.

Fetch Official Documentation

Once versions are identified, the developer retrieves the precise documentation page—not the homepage—for the required pattern. The guidelines in skills/source-driven-development/SKILL.md【L66-L74】establish a strict hierarchy: official documentation first, then official blogs or changelogs, then standards. Third-party blogs and Stack Overflow are explicitly excluded from the fetch step.

# Using curl to fetch the relevant doc section (illustrative)

curl -s https://react.dev/reference/react/useActionState#usage > useActionState.md

This fetch produces the authoritative contract that governs the implementation phase.

Implement with Authority

Implementation must mirror the signatures, usage examples, and deprecation warnings found in the fetched documentation. If the official docs conflict with existing codebase patterns, the developer surfaces the discrepancy rather than silently overriding it. The conflict-handling protocol in skills/source-driven-development/SKILL.md【L97-L119】requires presenting both options to the user with full context.

// Existing code uses useState for loading, but docs recommend useActionState
// Conflict detected – ask the user which approach to adopt
/*
CONFLICT DETECTED:
Existing: useState for form loading
Docs (React 19): useActionState (Source: https://react.dev/reference/react/useActionState#usage)
Options:
A) Adopt useActionState (aligned with current docs)
B) Keep useState (preserves existing code)
→ Which do you prefer?
*/

This prevents technical debt from propagating outdated patterns across new features.

Cite Your Sources

Every framework-specific construct must carry a citation comment containing a full URL (preferably a deep link) and optionally a quoted excerpt. The citation format specified in skills/source-driven-development/SKILL.md【L26-L34】creates immediate traceability for reviewers.

// React 19 form handling – source‑driven implementation
// Source: https://react.dev/reference/react/useActionState#usage
import { useActionState } from 'react';

function OrderForm() {
  const [state, formAction, isPending] = useActionState(submitOrder, {
    name: '',
    address: '',
  });

  return (
    <form action={formAction}>
      <input name="name" value={state.name} onChange={/* … */} />
      <input name="address" value={state.address} onChange={/* … */} />
      <button disabled={isPending}>Submit</button>
    </form>
  );
}

These comments serve as living documentation that survives refactors and code reviews.

Why Source-Driven Development Matters

Adopting this approach delivers three critical advantages for production systems:

• Accuracy: Official documentation reflects deprecations, migrations, and new APIs for each specific release, eliminating guesswork about whether a method still exists in version 19 versus version 18.
• Trust: Deep-link citations allow reviewers to verify rationale in seconds, replacing "I think this works" with "This is the documented pattern."
• Future-proofing: When dependencies upgrade, the citation URLs surface breaking changes immediately. Teams can diff their implemented code against the latest documentation rather than discovering incompatibilities at runtime.

Red Flags and Anti-Patterns

The skills/source-driven-development/SKILL.md file【L75-L81】identifies specific violations that undermine the methodology:

• Implementing framework code without first identifying the installed version.
• Citing non-authoritative sources like Medium tutorials or GitHub issue comments.
• Using deprecated APIs that the official documentation has already flagged for removal.

These anti-patterns create invisible debt that compounds across the codebase.

Summary

• Source-driven development is a four-step workflow (Detect → Fetch → Implement → Cite) defined in addyosmani/agent-skills.
• Always parse package.json, pyproject.toml, or go.mod to establish version context before coding.
• Fetch documentation from official sources only, avoiding Stack Overflow or third-party blogs.
• Surface conflicts between existing code and documentation rather than silently choosing one.
• Cite every framework construct with a full URL and optional excerpt to maintain traceability.

Frequently Asked Questions

What makes source-driven development different from standard development?

Standard development often relies on muscle memory, copied snippets, or community tutorials that may reference outdated API versions. The source-driven development approach requires explicit version detection and official documentation verification before any implementation, ensuring that every line of framework-specific code aligns with the currently installed dependency's authoritative contract.

How do I handle conflicts between existing code and official documentation?

When the fetched documentation contradicts patterns already present in the codebase, you must surface the conflict explicitly rather than auto-correcting. As implemented in skills/source-driven-development/SKILL.md【L106-L119】, present both the existing approach and the documented approach with their respective sources, then let the user or reviewer decide which pattern to adopt for the new implementation.

Which sources are considered authoritative in source-driven development?

The hierarchy is strict: official documentation sites (e.g., react.dev, docs.python.org) are primary sources, followed by official blogs and changelogs maintained by the framework authors, then formal standards specifications. Stack Overflow answers, Medium articles, and third-party tutorials are explicitly excluded from the fetch step because they often lag behind current releases or contain inaccurate adaptations.

Where is the source-driven development workflow defined in the repository?

The complete specification resides in skills/source-driven-development/SKILL.md within the addyosmani/agent-skills repository. This file defines the Detect, Fetch, Implement, and Cite phases along with line-specific guidance for citation formats (lines 26-34), version detection (lines 38-49), and conflict handling (lines 97-119).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}