feat: initial

[mfreeman451]

"The Guided Developer": A Product Requirements Document for guided.dev

A Protocol and Service for Building Great and Secure Software with AI Agents.

1. Introduction

The Problem: Large Language Models (LLMs) are revolutionizing code generation, but they operate in a vacuum. They are powerful but unguided, often producing code that is functional but naive in its architecture, security, and scalability. Developers, especially those learning new domains, need more than just code; they need wisdom and direction. Crucially, there is no standardized way for an LLM-powered coding agent to discover and interact with external sources of best-practice knowledge.

The Vision: guided.dev will provide the two missing pieces: a trusted source of opinionated guidance and a clear protocol for AI agents to consume it. We will build a security-first knowledge base accessible via an MCP (Model Context Protocol) server. To bridge the gap between agents and our service, we will pioneer the AGENTS.md specification—a machine-readable file that instructs LLM agents on how to interact with our guidance service, enabling a new era of structured, secure, and expert-informed AI-assisted development.

The Opportunity: By creating both the "what" (the guidance) and the "how" (the protocol), we can establish guided.dev as a foundational layer in the emerging AI-native development stack. This will lead to higher-quality, more secure software and create a standardized ecosystem for AI agents to consume expert knowledge.

2. The AGENTS.md Protocol

The AGENTS.md file is the key to unlocking structured interaction. It is a file placed in a project's repository that acts as a guidebook for any visiting LLM agent.

• Purpose: To declare an endpoint for expert guidance and define the "skills" or capabilities of that endpoint. It's robots.txt for collaborative AI.
• Discoverability: An LLM agent, upon analyzing a project, will look for an AGENTS.md file to discover if specialized, context-aware guidance is available.
• Specification: The file will be written in a simple, machine-readable format like YAML.

Example AGENTS.md:

# AGENTS.md: This file instructs AI agents on how to interact with the guided.dev service.
version: "1.0"

# The endpoint for the Model Context Protocol (MCP) server.
mcp_server: "https://mcp.guided.dev/v1"

# A list of capabilities this server offers.
capabilities:
  - id: "tech_stack_recommendation"
    description: "Get opinionated advice on the best and most secure tech stack for a given use case."
    request_schema:
      intent: string # e.g., "build a web app"
      context: object # e.g., { "topic": "fantasy football tracker", "users": "small_group" }

  - id: "secure_coding_pattern"
    description: "Retrieve a secure code snippet or pattern for a specific technology and task."
    request_schema:
      technology: string # e.g., "python-sqlite"
      task: string # e.g., "database query"

  - id: "deployment_guidance"
    description: "Get recommendations for secure deployment patterns."
    request_schema:
      stack: array # e.g., ["streamlit", "sqlite"]
      requirements: object # e.g., { "user_load": "low", "custom_domain": "true" }

3. User Personas & Journey

User Personas

• Priya, the Pragmatic Prototyper: Wants her AI assistant to be "smarter" out of the box, leveraging project-specific best practices defined by her team's AGENTS.md.
• Alex, the Ambitious Apprentice: Benefits from an AI assistant that automatically discovers and uses guided.dev to teach him secure and modern patterns.
• "Agent Smith," the LLM Coding Assistant: Programmed to look for AGENTS.md files to upgrade its generic capabilities with specialized, high-fidelity information from services like guided.dev.

User Journey (Alex and "Agent Smith")

1. The Prompt: Alex: "I want to build a Python app to track my fantasy football league."
2. Protocol Discovery: The agent, "Agent Smith," begins its process. Before writing any code, it scans the project directory for an AGENTS.md file. It finds one and parses it.
3. MCP Interaction: The agent now knows the endpoint (https://mcp.guided.dev/v1) and the capabilities. It formulates a request based on the tech_stack_recommendation schema and sends it to the MCP server.
4. Opinionated & Secure Guidance: guided.dev returns a structured JSON response recommending Streamlit and SQLite, but also includes a security_advisories array with warnings about SQL injection and the importance of input validation.
5. Interactive, Guided Refinement: The agent uses this rich information to talk to Alex: "Okay, I've consulted our project's guide. For a fantasy football tracker, the recommended approach is a Streamlit web app with a SQLite database. The guide also stresses the importance of using parameterized queries to keep it secure. Does that sound good?"
6. Context-Aware Code Generation: As they proceed, the agent continues to use the secure_coding_pattern capability defined in AGENTS.md. When Alex asks to add a user login, the agent queries guided.dev for "best practices for authentication in Streamlit" and gets back secure, modern patterns.

4. Features

MVP (Minimum Viable Product)

• AGENTS.md Specification v1.0: A published, clear specification for the AGENTS.md file format.
• MCP Server & REST API: An API that implements the capabilities defined in the AGENTS.md spec.
• Knowledge Graph Database: A graph database populated with an initial set of guidance for Python web development, with a strong emphasis on the OWASP Top 10.
• Core Capabilities:
  • tech_stack_recommendation
  • secure_coding_pattern
  • deployment_guidance

Future Roadmap

• Expanded Capabilities: Add new skills to the AGENTS.md spec, such as dependency_check_guidance and secrets_management_patterns.
• Expanded Knowledge Domains: Add guidance for other stacks (JavaScript/TypeScript, Go, etc.).
• Community Contributions: Create a system for trusted community members and security researchers to contribute to the knowledge graph.
• IDE Integration: Build plugins for tools like VS Code that can parse AGENTS.md files and provide proactive guidance directly in the editor.

5. Technical Architecture

System Components

1. MCP Server / API Gateway: The public-facing endpoint defined in AGENTS.md, responsible for request handling and routing.
2. Query Engine: Interprets structured agent requests and translates them into openCypher queries for our knowledge graph.
3. Knowledge Graph Database: Our core knowledge base will be implemented as a multi-model database using PostgreSQL with the Apache AGE (A Graph Extension) extension. This provides a single, robust system for all our data needs.
4. Content Management Service: An internal tool for curating the guidance in the graph.

Database Technology: PostgreSQL + Apache AGE

We have explicitly chosen to build our knowledge graph on top of PostgreSQL, enhanced with the Apache AGE extension. This approach provides the power of a native graph database with the reliability and maturity of a world-class relational database.

• Unified Data Store: This architecture allows us to store our core graph data (nodes, edges) and any supporting relational data (e.g., user accounts, API usage logs) within the same database instance. This drastically simplifies operations, backups, and data governance.
• Expressive Graph Queries: Apache AGE adds native support for openCypher, the industry-standard graph query language. This allows us to write intuitive, powerful, and performant queries to traverse the complex relationships in our knowledge base, which is far superior to complex recursive SQL.
• Leveraging the Postgres Ecosystem: We inherit the full benefits of PostgreSQL, including ACID compliance, transactional integrity, excellent performance, a vast ecosystem of tools, and robust managed hosting options from all major cloud providers.

Data Model (Graph Database Schema)

This logical schema will be implemented directly within PostgreSQL using Apache AGE. Nodes and edges will be created as graph entities and queried via openCypher.

• Nodes: Concept, Technology, UseCase, BestPractice, DeploymentPattern, Vulnerability, SecurityControl.
• Edges (Relationships): RECOMMENDED_FOR, HAS_BEST_PRACTICE, HAS_VULNERABILITY, MITIGATED_BY, IMPLEMENTS_CONTROL.

This model is designed to answer complex questions like, "What is the recommended technology for this use case, what are its common vulnerabilities, and what best practices implement the controls to mitigate them?"

6. Content & Validation Strategy

Our guidance is our product. It must be trustworthy and current.

• Content Sourcing: Initial content will be curated by a team of experienced software architects and security professionals, drawing from sources like the OWASP Foundation.
• Validation Process: All new guidance will undergo a multi-disciplinary review for architectural soundness and security correctness.
• Continuous Updating: We will have a dedicated process to keep pace with new technologies and emerging security threats.

7. Success Metrics

• Protocol Adoption: The number of public repositories containing an AGENTS.md file pointing to our service.
• API Usage: Number of API calls from unique agents/clients.
• Developer Satisfaction: Feedback from developers who find their AI assistants more helpful and secure.
• Knowledge Base Growth: Growth in the number and quality of nodes and edges in our graph.
• Partnerships: Integration with major LLM providers and AI agent frameworks.