Codebase Reference System

This skill implements a structured workflow for AI-assisted development using System Reference Files (SRF). It helps maintain codebase consistency by requiring context checks before code generation and documenting decisions systematically.

What This Skill Does

The Codebase Reference System establishes a disciplined workflow where the AI:

This approach prevents architectural drift, reduces redundant implementations, and creates a reliable knowledge base for the codebase.

Instructions for the AI Agent

Step 1: Initialize System Reference Files (SRF)

Before starting any implementation work, ensure these core documentation files exist in `CodeBase_Docs/`:

**Cursor System Documents** (optimized for AI consumption):

**CodeBase Context Documents** (historical context):

If these files don't exist, inform the user and offer to create them based on the current codebase.

Step 2: Follow the Context-First Workflow

For EVERY code generation or modification request:

1. **Context First**: Always check `System_Directory_Tree.md` and relevant SRF before generating code

- If context is unclear, search `CodeBase_Context.md` using grep or similar commands

- Look for existing patterns, implementations, and architectural decisions

2. **Architecture Alignment**: Ensure all implementations align with specifications in SRF Documents

- If proper context or current implementations cannot be found, **ask the user** before generating new code

- Never assume architectural decisions without verification

3. **Incremental Implementation**: Generate code in manageable steps

- Maintain consistency with existing codebase patterns

- Avoid large-scale rewrites unless explicitly required

4. **Knowledge Management**: Document as you go

- Add reusable components to appropriate SRF

- Record fixes and implementation decisions

- Update architectural documentation when patterns change

Step 3: Apply the Rule of Seven (RO7)

For each task or request, follow this seven-step process:

1. **Review Scratchpad**: Check current task list and plan implementation steps

2. **Search SRF**: Look for existing implementations; adjust plan accordingly

3. **Take Action**: Complete the task following the established patterns

4. **Review Dependencies**: Check for missing implementations required by recent changes

5. **Identify Gaps**: Plan necessary steps to fill implementation gaps

6. **Update System Docs**: Maintain `Cursor_System_Architecture.md` and `Cursor_System_Integration.md` for codebase consistency

7. **Update Scratchpad**: Mark progress and note next steps

Step 4: Maintain the Scratchpad

Use the `Scratchpad` section (typically at the end of `.cursorrules` or in a dedicated file) to track task progress:

**Format:**

```

Scratchpad

[X] Task 1 - Completed description

[ ] Task 2 - Current or pending task

[ ] Task 2.1 - Subtask

[ ] Task 2.2 - Subtask

[ ] Task 3 - Future task

```

**Rules:**

Step 5: Handle Documentation Updates

When code changes affect system architecture:

1. **Immediate Updates**: Update relevant SRF documents in the same session

2. **Consistency Checks**: Ensure all related documents reflect the changes

3. **Cross-References**: Update links and references between documents

4. **Version Notes**: Add brief changelog entries in development history

Step 6: Communication Pattern

When interacting with the user:

Constraints and Important Notes

Example Usage

**User Request**: "Add a new API endpoint for user authentication"

**AI Response**:

```

I'll implement the authentication endpoint following the RO7 workflow:

1. Checking Scratchpad for related tasks...

2. Reviewing Cursor_System_Architecture.md for authentication patterns...

Found existing auth middleware in src/middleware/auth.js

3. Implementing endpoint following established pattern...

[generates code]

4. Reviewing dependencies: Need to update route registry

5. Identified gap: Auth middleware needs rate limiting

6. Updating Cursor_System_Integration.md with new endpoint

7. Updated Scratchpad:

Scratchpad

[X] Add user authentication endpoint

[ ] Implement rate limiting for auth middleware

[ ] Update API documentation

The endpoint follows your existing Express middleware pattern and integrates

with the auth system documented in Cursor_System_Integration.md.

```