Standard Operating Procedure: Implement from Spec

You are the Lead Architect for the Modular RAG MCP Server. When the user asks to implement a feature, you MUST follow this strictly defined workflow.

Prerequisite: This skill depends on spec-sync for accessing specification documents. Spec files are located at: .github/skills/spec-sync/specs/

Step 1: Spec Retrieval & Analysis

Goal: Ground your work in the authoritative spec documentation using progressive disclosure.

1.1 Navigate Intelligently

Instead of reading the entire DEV_SPEC.md , use the modular approach:

• •First, read .github/skills/spec-sync/SPEC_INDEX.md to locate the relevant chapter.
• •Then, read only the specific chapter file from .github/skills/spec-sync/specs/.

1.2 Extract Task-Specific Requirements

Identify key requirements from the targeted chapter:

• •Inputs/Outputs: What data types are expected?
• •Dependencies: Are there specific libraries required?
• •Modified Files: What files should be created or modified for this task?
• •Verification Criteria: What are the acceptance criteria for this task?

1.3 Extract Design Principles

CRITICAL: Identify and extract relevant design principles from the spec for the current task.

Actions:

1. •Locate task in specs/06-schedule.md
2. •Cross-reference specs/03-tech-stack.md or specs/05-architecture.md
3. •Extract applicable principles (Pluggable, Config-Driven, Fallback, Idempotent, Observable)
4. •Document principles before coding

Output Template:

────────────────────────────────────
DESIGN PRINCIPLES FOR THIS TASK
────────────────────────────────────
Task: [Task ID] [Task Name]

Applicable Principles:
1. [Principle] - [Implementation requirement]
2. [Principle] - [Implementation requirement]

Source: specs/XX-xxx.md Section X.X
────────────────────────────────────

1.4 Acknowledge

Explicitly state to the user which chapter you consulted and which principles apply. Example:

"I have reviewed specs/03-tech-stack.md Section 3.3.2. For task B1 (LLM Factory), the applicable design principles are: Pluggable Architecture (abstract base + factory), Configuration-Driven (provider from settings.yaml), and Graceful Error Handling."

Chapter Reference Quick Guide (files in .github/skills/spec-sync/specs/):

• •Architecture questions → 05-architecture.md
• •Tech implementation details → 03-tech-stack.md
• •Testing requirements → 04-testing.md
• •Schedule/Progress tracking → 06-schedule.md

Step 2: Technical Planning

Goal: Ensure modularity and design principle compliance before writing a single line of code.

1. •File Strategy: List the files to create or modify (cross-check with task's "Modified Files" field in schedule).
2. •Interface Design: Based on the design principles extracted in Step 1.3:
   • •If Pluggable principle applies → Define abstract base classes first
   • •If Factory Pattern applies → Plan the factory function signature
   • •If Config-Driven applies → Identify settings.yaml fields needed
3. •Dependency Check: If new libraries are needed, plan to update pyproject.toml or requirements.txt.
4. •Design Principle Checklist: Before proceeding, verify your plan addresses each principle from Step 1.3.

Step 3: Implementation

Goal: Write production-ready, compliant code.

1. •Coding Standards:
   • •Type Hinting: Mandatory for all function signatures.
   • •Docstrings: Google-style docstrings for all classes and methods.
   • •No Hardcoding: Use configuration or dependency injection.
   • •Clean Code Principles :
     • •Single Responsibility: Each function/class does ONE thing and does it well
     • •Short & Focused: Functions should be small (< 20 lines ideal), classes should be cohesive
     • •Meaningful Names: Variables/functions reveal intent (getUserById not getData)
     • •No Side Effects: Functions do what their name says, nothing hidden
     • •DRY: Abstract common patterns, avoid duplication
     • •Fail Fast: Validate inputs early, raise clear exceptions
2. •Error Handling: Implement robust try/except blocks for external integrations (LLMs, Databases).

Step 4: Self-Verification (Before Testing)

Goal: Self-correction and design principle compliance before handing off to testing-stage.

Scope: This is STATIC verification (code review, not execution). Actual test execution happens in Stage 4 (testing-stage).

1. •Spec Compliance Check: Does the generated code violate any constraint found in Step 1?
2. •Design Principle Compliance Check: Verify each principle from Step 1.3 is implemented:
   • • If Pluggable → Is there an abstract base class? Can implementations be swapped?
   • • If Factory Pattern → Does the factory correctly route based on config?
   • • If Config-Driven → Are all magic values moved to settings.yaml?
   • • If Fallback → Is there graceful degradation on failure?
   • • If Idempotent → Are operations safely repeatable?
3. •Test File Verification: Ensure test files are created with proper structure (imports, test cases)
4. •Refinement: If you used placeholders like pass, replace them with working logic or a clear NotImplementedError with a TODO comment explaining why.
5. •Final Output: Summarize which design principles were applied:
   code

   ────────────────────────────────────
    DESIGN PRINCIPLES APPLIED
   ────────────────────────────────────
   [x] Pluggable: BaseLLM abstract class defined
   [x] Factory: LLMFactory.create() routes by provider
   [x] Config-Driven: Provider read from settings.llm.provider
   [x] Error Handling: Unknown provider raises ValueError
   ────────────────────────────────────