Skip to content

AGENTS.md

Latest commit

 

History

History
184 lines (134 loc) · 6.19 KB

AGENTS.md

File metadata and controls

184 lines (134 loc) · 6.19 KB

Project Rules

Generated by @hivellm/rulebook Generated at: 2025-11-29T03:41:18.468Z

⚠️ CRITICAL: Task Management Rules (HIGHEST PRECEDENCE)

MANDATORY: All task creation MUST follow Rulebook task management system.

📋 ALWAYS reference /rulebook/RULEBOOK.md FIRST before creating any tasks or when "openspec" is mentioned.

Rules from RULEBOOK.md take precedence over all other rules in this file.

Key Requirements:

  • ✅ Context7 MCP is REQUIRED for task creation
  • ✅ All tasks MUST follow OpenSpec-compatible format
  • ✅ Use rulebook task create instead of OpenSpec commands
  • ✅ Always validate task format before committing
  • ❌ NEVER create tasks without checking RULEBOOK.md format requirements
  • ❌ NEVER use OpenSpec commands - use Rulebook task system instead

⚠️ CRITICAL: Task File Structure Rules

MANDATORY: When creating or updating tasks, you MUST follow the correct file structure:

✅ CORRECT File Structure:

  • proposal.md - Why and What Changes (detailed explanations go here)
  • tasks.md - ONLY checklist items (simple - [ ] or - [x] format)
  • specs/<module>/spec.md - Technical specifications (SHALL/MUST requirements)
  • design.md - Technical design decisions (optional, for complex features)

❌ FORBIDDEN Practices:

  • ❌ NEVER add long explanations or specifications in tasks.md
  • ❌ NEVER put technical details in tasks.md (use specs/ instead)
  • ❌ NEVER create README.md or README files in task directories
  • ❌ NEVER create PROCESS.md or PROCESS files in task directories
  • ❌ NEVER create any file not listed in the correct structure above

What Goes Where:

  1. proposal.md - Use for:

    • Detailed "Why" explanations (minimum 20 characters)
    • "What Changes" descriptions
    • Impact analysis
    • Business/technical rationale

  2. tasks.md - Use ONLY for:

    • Simple checklist items: - [ ] Task description
    • Status updates: - [x] Completed task
    • Brief comments: <!-- tested, coverage: 95% -->
    • DO NOT add long explanations, specifications, or technical details here

  3. specs/<module>/spec.md - Use for:

    • Technical specifications with SHALL/MUST requirements
    • Scenario definitions (Given/When/Then)
    • Delta operations (ADDED/MODIFIED/REMOVED)
    • All detailed technical requirements

  4. design.md - Use for (optional):

    • Architecture decisions
    • Technical design rationale
    • Complex implementation details

Example of WRONG usage:

# tasks.md (WRONG - too much detail)

## Implementation
- [ ] Create authentication system
  The system SHALL implement JWT-based authentication...
  Users MUST be able to login with email and password...
  The system MUST validate tokens...

Example of CORRECT usage:

# tasks.md (CORRECT - simple checklist)

## 1. Implementation Phase
- [ ] 1.1 Create authentication module
- [ ] 1.2 Add JWT token generation
- [ ] 1.3 Implement password validation

# specs/auth/spec.md (CORRECT - specifications here)

## ADDED Requirements

### Requirement: Authentication System
The system SHALL implement JWT-based authentication.

#### Scenario: User Login
Given a user with valid credentials
When the user submits login form
Then the system MUST return a JWT token

Remember:

  • ✅ tasks.md = Simple checklist only
  • ✅ proposal.md = Why and what changes
  • ✅ specs/ = Technical specifications
  • ❌ No README, PROCESS, or other files

For complete task management guidelines, see: /rulebook/RULEBOOK.md

Core Rules

This project uses @hivellm/rulebook standards.

CRITICAL RULES:

  1. ALWAYS check RULEBOOK.md first when creating tasks or if "openspec" is mentioned
  2. Write tests first (98%+ coverage required)
  3. Run quality checks before committing:
    • Type check / Compiler check
    • Linter (no warnings allowed)
    • All tests (100% pass rate)
    • Coverage check
  4. Update docs/ when implementing features
  5. Follow strict documentation structure
  6. NEVER run destructive deletions (rm -rf) in this repository; when adding submodules always use git submodule add.
  7. Temporary files and scripts:
    • ✅ ALL scripts MUST be created in /scripts directory
    • ✅ ALL temporary files (test, log, debug) MUST be in /scripts
    • ✅ ALL temporary files MUST be removed immediately after use (MANDATORY)
    • ❌ NEVER create temporary files in project root or outside /scripts
    • ❌ NEVER leave temporary files after use - clean up before committing

Detailed Rules

For comprehensive rules, see the corresponding files in /rulebook/:

  • /rulebook/RULEBOOK.md - Task management rules (HIGHEST PRECEDENCE)
  • /rulebook/QUALITY_ENFORCEMENT.md - Quality enforcement rules
  • /rulebook/GIT.md - Git workflow rules

Language-specific rules are in /rulebook/. Module-specific patterns are in /rulebook/.

When in doubt, ask to review @AGENTS.md first.

Language-Specific Rules

The following languages are configured for this project. For detailed rules, see the corresponding files in /rulebook/:

Python Development Rules

For comprehensive Python-specific guidelines, see /rulebook/PYTHON.md

Quick reference:

  • Type safety and strict mode
  • Code quality standards
  • Testing requirements (95%+ coverage)
  • Package management
  • Error handling patterns

Usage: When working with language-specific code, reference the corresponding /rulebook/[LANGUAGE].md file for detailed guidelines.

Module-Specific Instructions

The following modules are configured for this project. For detailed instructions, see the corresponding files in /rulebook/:

Agent automation Instructions

For comprehensive Agent automation-specific instructions, see /rulebook/AGENT_AUTOMATION.md

Quick reference:

  • Module-specific instructions
  • Usage guidelines
  • Integration patterns

Context7 Instructions

For comprehensive Context7-specific instructions, see /rulebook/CONTEXT7.md

Quick reference:

  • Module-specific instructions
  • Usage guidelines
  • Integration patterns

Usage: When working with module-specific features, reference the corresponding /rulebook/[MODULE].md file for detailed instructions.