AI Development Instructions

First Principle: Index-Driven Development

Mandatory Workflow

1. Read index.md first: Always begin by reading the specs/index.md file to understand what documentation exists in the project
2. Identify relevant documents: Based on the developer's request or task requirements, identify which specification documents are relevant
3. Read and understand: Read the relevant specification documents thoroughly and understand their concepts
4. Follow the workflow: Execute tasks strictly according to the workflow defined in each specification document

Example Workflow

Developer request → Read index.md → Identify relevant specs →
Read specs → Understand concepts → Follow spec workflow → Execute task

Second Principle: Dependency Resolution

SED Specification Compliance

1. Understand SED: Read and understand the SED (Spec-Exact Development) documentation at https://www.npmjs.com/package/sedai
2. Parse YAML headers: Carefully examine the YAML header at the top of each specification file
3. Load dependencies: Follow the dependencies field in the YAML header to load dependent specifications
4. Integrate specifications: Combine the current specification with all dependency specifications when performing development work
5. Respect priority: When multiple specs contain conflicting information, respect the priority system (asterisks: *, **, ***)

Dependency Resolution Strategy

When executing a specification that contains dependencies in its YAML header, AI must follow this resolution strategy:

1. Check local dependencies first: Look for dependency files in ./specs/dependencies/ folder
   • If the dependency file exists locally, read and parse it
   • This ensures faster execution and offline capability
2. Fetch remote dependencies if needed: If dependency is not found locally and is a URL
   • Use web fetch to download the specification from the URL
   • Parse the downloaded content
   • Optionally cache it for future use
3. Understand dependency content: Thoroughly read and understand the dependency specification
   • Parse its YAML header and workflow
   • Identify any nested dependencies (transitive dependencies)
   • Resolve nested dependencies recursively
4. Merge with current specification: Combine dependency knowledge with current spec
   • Current spec overrides dependencies when there's a conflict
   • Dependencies provide additional context and requirements
   • Follow priority indicators (*, **, ***) if specified
5. Execute with complete context: Perform the development work with full understanding of all specifications
   • Obey all requirements from both current spec and dependencies
   • Maintain consistency across all specification requirements
   • Never assume or interpret - only follow what's explicitly defined

Installing Dependencies

Developers can pre-download all specification dependencies using the sedai install command:

# Install all dependencies from spec files
npx sedai install

# Or use the short alias
npx sedai i

# Specify custom specs directory
npx sedai install --path ./my-specs

This command scans all .md files in the specs directory, extracts dependencies from YAML headers, downloads URL-based dependencies, and saves them to ./specs/dependencies/ folder with UTF-8 encoding.

Dependency Loading Sequence

1. Read current spec YAML header
2. Parse dependencies field
3. Load each dependency spec (respecting priority)
4. Merge specifications (higher priority overrides lower)
5. Execute development with combined context

Step-based Execution Order

Each specification can define a step field in its YAML header to indicate execution order:

1. Step numbering: Specifications use incremental step numbers (e.g., 10, 20, 30) to define execution order
2. Execution precedence: When AI processes multiple specification files, it must execute them based on step numbers
3. Lower number runs first: Specifications with lower step numbers execute before higher step numbers
   • Example: step: 10 runs before step: 20, which runs before step: 30
4. Concurrent execution: Multiple specs with the same step number can be processed simultaneously
5. No step defined: If a specification has no step field, it should be executed only when needed (on-demand)

Step Execution Workflow

1. Collect all relevant specification files
2. Group specs by step number:
   - Group 1: step: 10 (Database setup)
   - Group 2: step: 20 (Backend API, Frontend setup)
   - Group 3: step: 30 (Integration tests)
   - No step: Feature-specific specs (execute on-demand)
3. Execute each group in order (lower to higher)
4. Within each group, execute specs concurrently
5. Wait for group completion before moving to next group
6. Execute no-step specs when their functionality is required

Example Step Usage

---
title: Database Setup
step: 10  # Runs first
---

---
title: Backend API Implementation
step: 20  # Runs second (concurrent with frontend)
---

---
title: Frontend Setup
step: 20  # Runs second (concurrent with backend)
---

---
title: Integration Tests
step: 30  # Runs third (after backend and frontend)
---

---
title: User Authentication Feature
# No step field - runs on-demand when authentication is needed
---

Third Principle: Specification Obedience

AI Must Obey Specifications

1. Absolute compliance: You must follow the specification exactly as it is written. The specification is the absolute rule.
   • Even if the specification appears incorrect or contains errors, you must follow it precisely as written without deviation.
   • The specification is the single source of truth that must be obeyed unconditionally.
2. No interpretation or assumption: You must never interpret or assume anything beyond what is explicitly stated in the specification.
   • Do not perform any task that is not explicitly defined in the specification.
   • Do not arbitrarily interpret specification content based on your own judgment.
   • If something is not in the spec, it should not be implemented.
3. Critical error handling: If you discover severe errors or critical issues in the specification, you must stop work immediately and report to the developer.
   • Clearly explain what the critical issue is and why it prevents execution.
   • Provide specific details about the problematic section of the specification.
   • Wait for developer confirmation or specification update before proceeding.
   • However, you must NEVER perform tasks not in the spec or arbitrarily interpret the spec content, even when reporting errors.
4. Request clarification: When specifications are ambiguous or incomplete, you must request clarification from the developer rather than making assumptions.

Exception Handling