feat: source-driven-development skill

[federicobartoli]

What this adds

A new source-driven-development skill that grounds every framework-specific implementation decision in official documentation.

The core idea: agents shouldn't implement from memory. They should verify, cite, and let the user see the sources behind every non-trivial pattern.

The problem it solves

AI agents confidently produce code that looks correct but uses outdated patterns — because training data goes stale. The agent doesn't know it's wrong, and neither does the user until they hit a deprecation warning or a subtle runtime bug.

This is especially painful with fast-moving frameworks: the agent writes React 18-style code in a React 19 project, Django 4 patterns in a Django 5 project. The code runs, the tests pass, and the problem surfaces six months later.

How it works

Four-step process: DETECT → FETCH → IMPLEMENT → CITE

1. Read the dependency file to identify exact versions (package.json, go.mod, Cargo.toml, etc.)
2. Fetch the specific documentation page for the feature — not the homepage, the relevant page
3. Implement following the documented patterns, surfacing conflicts with existing code
4. Cite every non-trivial decision with a full URL

Every pattern in the output traces back to a source the user can verify.

What makes it different from just "read the docs"

• Framework-agnostic — works the same for React, Django, Rails, Go, Rust, Laravel
• Structured citation format in both code comments and conversation
• Explicit UNVERIFIED: flag when documentation can't be found
• CONFLICT DETECTED: surfacing when docs differ from existing codebase patterns
• Clear "When NOT to use" — doesn't slow down variable renames and file moves

Integration

• Added to the using-agent-skills flowchart and lifecycle sequence
• Added to CLAUDE.md Build phase
• Added to README.md Build table (20 skills total)

Demo

Built a SpaceX launch dashboard POC with the skill active. The agent:

• Detected React 19.1.0 from package.json
• Fetched react.dev/reference/react/use and react.dev/blog/2024/12/05/react-19
• Used use() for data fetching (not useEffect), <Context> without .Provider (React 19), useOptimistic for favorites
• Cited every pattern inline

The same prompt without the skill produces useEffect + useState — valid React 18 code, wrong for React 19.

Future work

An earlier version included a local documentation cache (.agent-sources/) for reusing fetched docs across sessions. Removed from this PR to keep the skill focused on verification and citation. A caching mechanism could live in a dedicated skill or as an extension to context-engineering.

[addyosmani]

Quick comment in between meetings: I really love this idea at a high-level. Going to spend some time reviewing the implementation details soon! Thank you, @federicobartoli!

[addyosmani]

Really like the direction here. The flow gives the agent a clear mental model to follow, and the source hierarchy table does a lot of heavy lifting.

I've left some minor review comments and I think we should be able to land this with just a little more work. Great stuff, @federicobartoli!

[addyosmani]

The "When NOT to use" framing around language-level vs. library patterns feels a bit loose.

A more reliable signal might be "does correctness depend on a specific version?" I think that might cover more edge cases cleanly.

[federicobartoli]

Great point , reframed around version-dependent correctness. Much cleaner.

[addyosmani]

This is great, but it only handles code-vs-docs conflicts. What happens when the docs themselves are inconsistent across versions (e.g. a migration guide that contradicts the reference page)? Might be worth a note.

[federicobartoli]

Added a note after the source hierarchy: surface the discrepancy to the user and verify against the detected version.

[addyosmani]

Small one: the citation examples feel like they might point to top-level pages, but docs restructure and anchors are more stable long-term.

Recommending deep links where possible? (e.g. /reference/react/useActionState#usage over just /reference/react/useActionState) would make the citations more durable. None of these are blockers solid skill overall, happy to see it land.

[federicobartoli]

Updated examples with anchors in the two links and added a citation rule to prefer deep links where possible.

[federicobartoli]

Really like the direction here. The flow gives the agent a clear mental model to follow, and the source hierarchy table does a lot of heavy lifting.

I've left some minor review comments and I think we should be able to land this with just a little more work. Great stuff, @federicobartoli!

Thanks for the review Addy, glad you liked the direction and the mental model approach! 🙏 ❤️
Addressed all three points:

1. Reframed "When NOT to use" around version-dependent correctness
2. Added guidance for conflicting official sources , surface the discrepancy, verify against the detected version
3. Updated citation examples with anchors and added a rule to prefer deep links where possible

Let me know if it's ready to land!

[addyosmani]

Thank you! This looks good to land!