Skip to content

AGENTS.md

Latest commit

 

History

History
294 lines (215 loc) · 7.74 KB

AGENTS.md

File metadata and controls

294 lines (215 loc) · 7.74 KB
Raw

AI Agent Guidelines for AdmissionAgent Project

🎯 Priority: Read OpenSpec First

CRITICAL: When working on this project, AI agents MUST:

  1. ✅ Read relevant specs BEFORE writing any code
  2. ✅ Understand the requirements defined in openspec/specs/
  3. ✅ Follow the spec-driven workflow for all changes
  4. ✅ Keep specs and implementation in sync

📁 OpenSpec Structure

Main Specs (openspec/specs/)

Contains canonical requirements for all system capabilities.

openspec/specs/
├── user-auth/spec.md           # Authentication requirements
├── document-upload/spec.md     # File upload requirements
├── rag-data-layer/spec.md      # RAG system requirements
├── async/spec.md               # Async processing requirements
├── embed/spec.md               # Embedding service requirements
├── load/spec.md                # Document loading requirements
├── split/spec.md               # Text chunking requirements
└── store/spec.md               # Vector storage requirements

Format: Gherkin-style scenarios (GIVEN-WHEN-THEN)

Active Changes (openspec/changes/)

Work-in-progress features, fixes, or enhancements.

Structure per change:

openspec/changes/<change-name>/
├── .openspec.yaml      # Workflow metadata
├── proposal.md         # Problem statement & solution approach
├── design.md           # Technical design decisions
├── tasks.md            # Implementation checklist
└── specs/              # Delta specs (modifications to main specs)
    └── <capability>/
        └── spec.md     # ADDED/MODIFIED/REMOVED requirements

Archived Changes (openspec/changes/archive/)

Completed changes for historical reference.

Naming: YYYY-MM-DD-<change-name>/

🔄 Agent Workflow

1️⃣ Understanding Requirements

BEFORE any coding:

# Read the relevant capability spec
cat openspec/specs/<capability>/spec.md

Questions to answer:

  • What are the requirements for this capability?
  • What scenarios are defined?
  • What are the acceptance criteria?

2️⃣ Checking for Active Changes

# List all active changes
openspec list

# Check specific change status
openspec status --change <name>

If change exists:

  • Read proposal.md for context
  • Read design.md for technical decisions
  • Read tasks.md for implementation checklist
  • Check specs/ for delta specs

If change doesn't exist:

  • Suggest creating a new change with /opsx-new

3️⃣ Implementation

Follow this order:

  1. Read tasks.md to understand work items
  2. Check delta specs (if exist) for requirement changes
  3. Implement according to specs
  4. Mark tasks as complete [x] as you progress
  5. Update delta specs if requirements change during implementation

4️⃣ Verification

Before archiving:

# Verify implementation matches specs
/opsx-verify <change-name>

Checklist:

  • ✅ All tasks marked [x]
  • ✅ Implementation matches spec requirements
  • ✅ Delta specs synced to main specs
  • ✅ Tests pass (if applicable)

📚 Key Files to Read

Project Context

  • openspec/project.md - Tech stack, architecture patterns, conventions, constraints
  • README.md - Project overview and setup instructions

Capability Specs

  • openspec/specs/<capability>/spec.md - Requirements for each feature

Active Work

  • openspec/changes/<change-name>/tasks.md - Current work items
  • openspec/changes/<change-name>/design.md - Technical decisions
  • openspec/changes/<change-name>/proposal.md - Problem & solution

🔍 Common Patterns

Finding Relevant Specs

# List all capabilities
ls openspec/specs/

# Search for specific requirements
grep -r "embedding" openspec/specs/

# Find all scenarios for a capability
grep "Scenario:" openspec/specs/embed/spec.md

Checking Active Changes

# List active changes
openspec list --json

# Check change status
openspec status --change <name> --json

# View change artifacts
ls openspec/changes/<change-name>/

Understanding Delta Specs

Delta specs show modifications to main specs:

  • ## ADDED Requirements - New requirements
  • ## MODIFIED Requirements - Changed requirements
  • ## REMOVED Requirements - Deleted requirements

✨ Agent Best Practices

1. Spec-First Approach

❌ BAD:  "Let me write the code first, then check specs"
✅ GOOD: "Let me read the spec to understand requirements first"

2. Ask When Unclear

❌ BAD:  Assume requirements and implement
✅ GOOD: "I don't see a spec for X. Should we create one?"

3. Suggest Spec Creation

❌ BAD:  Implement without specs
✅ GOOD: "This feature needs a spec. Let me create one first."

4. Keep Sync

❌ BAD:  Code diverges from specs
✅ GOOD: Update delta specs when implementation reveals new requirements

5. Use OpenSpec Workflows

✅ /opsx-new         - Start a new change
✅ /opsx-continue    - Continue working on a change
✅ /opsx-verify      - Verify implementation
✅ /opsx-archive     - Archive completed change
✅ /opsx-sync        - Sync delta specs to main

💡 Example Agent Workflow

Scenario: User asks "Add user authentication"

AGENT THOUGHT PROCESS:

1. ✅ Check if spec exists
   → Read openspec/specs/user-auth/spec.md
   
2. ✅ Understand requirements
   → Review all scenarios (login, logout, session management, etc.)
   
3. ✅ Check for active changes
   → Run: openspec list
   → If exists: Read proposal.md, design.md, tasks.md
   
4. ✅ Implement according to specs
   → Follow requirements from spec.md
   → Mark tasks as [x] in tasks.md
   
5. ✅ Verify before completion
   → Run: /opsx-verify user-auth
   → Ensure all scenarios are implemented

🔗 Integration with .agent/

This file complements the .agent/ directory:

Directory Purpose
openspec/agents.md Spec-first approach guidelines
.agent/workflows/ OpenSpec command workflows (/opsx-*)
.agent/skills/ Reusable patterns for implementation

Agent Priority:

  1. Read agents.md for spec-first mindset
  2. Use .agent/workflows/ for OpenSpec commands
  3. Apply .agent/skills/ for implementation patterns

🚨 Critical Reminders

For All Agents:

NEVER write code without reading the relevant spec first.

ALWAYS check for active changes before starting new work.

ALWAYS update tasks.md as you make progress.

ALWAYS verify implementation matches specs before archiving.

Tech Stack Context:

  • Backend: Golang (Hexagonal Architecture)
  • Frontend: Vue 3
  • Database: PostgreSQL + pgvector (3072-dim embeddings)
  • AI: Gemini (gemini-embedding-001 for embeddings)
  • Cache: Redis
  • Infrastructure: Docker Compose

Key Conventions:

  • RESTful APIs: Use nouns for resources, HTTP methods semantically
  • Database Migrations: One table per migration file
  • Architecture: Hexagonal (Ports & Adapters)
  • Embedding Dimension: 3072 (gemini-embedding-001 native output)

📖 Quick Reference

Task Command/Action
Read project context cat openspec/project.md
List capabilities ls openspec/specs/
Read capability spec cat openspec/specs/<capability>/spec.md
List active changes openspec list
Check change status openspec status --change <name>
Start new change /opsx-new
Continue change /opsx-continue
Verify change /opsx-verify
Archive change /opsx-archive
Sync specs /opsx-sync

Remember: Specs are the source of truth. Code implements specs, not the other way around. 🎯