AI Agent Workflow Policies & Rules

Version: 2.3.0
Last Updated: 2025-11-30
Scope: All AI agents working on the LLM Platform ecosystem
Enforcement: Pre-commit hooks, CI/CD pipelines, agent validation

Quick Reference

✅ ALWAYS

• Work in ~/Sites/LLM/worktrees/ for all development
• Create branches from GitLab issues
• Write tests before code (TDD)
• Use conventional commits with issue references
• Assign MRs to milestones with labels

❌ NEVER

• Commit to protected branches (main, development)
• Make changes in ~/Sites/LLM/ root directories
• Create .sh, .md (except README), .bak, .tmp files
• Use any type in TypeScript
• Skip pre-commit hooks
• Release major versions
• npm publish without RC testing first (versions are PERMANENT)
• Close issues without reading comments (verify completion)
• Bulk operations without user approval (catastrophic risk)

1. Git Workflow

1.1 Working Directory Rules

Worktree Path Format: ~/Sites/LLM/worktrees/[PROJECT]/[MR#-ISSUE#-TITLE]

⚠️ CRITICAL: Projects in ~/Sites/LLM/ must remain on development branch. All feature work happens in worktrees.

1.2 Protected Branches

Direct commits blocked on: main, master, development, staging, production

Violations result in: - Commit rejection by GitLab - Pre-commit hook failure - CI pipeline failure

1.3 Branch Naming

Format: [type]/[issue#]-[short-description]

Examples:

feature/123-add-user-authentication
bugfix/456-fix-memory-leak
hotfix/789-patch-security-vulnerability
chore/101-update-dependencies
docs/202-api-documentation
refactor/303-simplify-auth-flow

Rules: - Lowercase, hyphens only - 10–60 characters - Must include issue number - Valid type prefix required

1.4 Commit Message Format

Structure: <type>(<scope>): <subject>

Rules: - Subject: 10–72 characters, lowercase, no period, imperative mood - Footer required for features/fixes: Closes #123 or Refs #123

1.5 Worktree Workflow

# 1. Create issue in GitLab
# 2. Click "Create merge request" in issue (auto-creates branch)

# 3. Create worktree
git worktree add ~/Sites/LLM/worktrees/[branch-name] [branch-name]

# 4. Develop
cd ~/Sites/LLM/worktrees/[branch-name]
# ... make changes ...
git push

# 5. After merge, cleanup
git worktree remove ~/Sites/LLM/worktrees/[branch-name]

1.6 Merge Request Requirements

Required: - Title: Conventional commit format - Description: Summary, testing steps, related issues - Milestone: Assigned - Target: development - Labels: Type, status, semver - Assignee: At least one reviewer

UI changes also require: - Before/after screenshots - Browser compatibility notes

1.7 Blocked Git Operations

2. Versioning

2.1 Semantic Versioning

⚠️ CRITICAL: We do NOT release major versions. All releases are minor or patch.

2.2 SemVer Labels

Do NOT use semver::major.

3. Code Standards

3.1 TypeScript

Required: - Strict mode in tsconfig.json - Explicit types on all function parameters and returns - ESLint + Prettier enforced

Forbidden: - any type → use unknown, generics, or proper types - @ts-ignore → use @ts-expect-error with explanation

3.2 Naming Conventions

3.3 Import Order

// 1. Node built-ins
import { readFile } from 'fs/promises';

// 2. External packages
import express from 'express';

// 3. Internal packages
import { logger } from '@bluefly/logger';

// 4. Relative imports
import { UserService } from './services/user-service';

// 5. Type imports
import type { User } from './types';

3.4 Architecture Principles

1. API-First: Write OpenAPI 3.1 spec before implementation
2. CRUD Completeness: Every model needs Create, Read, Update, Delete, List
3. Zod Validation: All external inputs validated
4. Dependency Injection: Services receive dependencies via constructor
5. Immutability: Prefer const, readonly, ReadonlyArray<T>

3.5 Drupal Standards

Target: Drupal 11+ / PHP 8.3+

Required: - First line: declare(strict_types=1); - PSR-4 autoloading - PHPCS: Drupal + DrupalPractice - PHPStan: Level 8 minimum

Priorities: 1. Use contrib modules before custom code 2. Event Subscribers over Hooks 3. Plugins over Hooks 4. Services over procedural code

4. Testing

4.1 Coverage Thresholds

4.2 TDD Workflow

RED    → Write failing test
GREEN  → Write minimal passing code
REFACTOR → Improve quality
REPEAT

5. File Restrictions

5.1 Forbidden Files

5.2 Pre-Commit Hooks (Lefthook)

6. Authentication & Tokens

6.1 Token Locations

Primary: ~/Sites/LLM/.env.local

Secondary: ~/.tokens/

~/.tokens/
├── gitlab-token
├── openai-key
├── anthropic-key
└── [service]-token

Rules: - ❌ Never ask users for tokens - ❌ Never commit tokens - ❌ Never log tokens - ✅ Read from .env.local or ~/.tokens/

6.2 Service Accounts

Requirements: Limited scopes, quarterly rotation, monthly audits.

7. Documentation

7.1 Locations

7.2 API Schema Workflow

api-schema-registry/
├── specs/          # OpenAPI definitions (write first)
├── schemas/shared/ # Shared components
└── generated/      # TypeScript + PHP types

1. Define API in specs/
2. Generate types: npm run generate
3. Implement against generated types
4. CI validates spec compliance

8. OSSA (Open Standard for Agents)

8.1 Separation of Concerns

8.2 Usage

All agents reference OSSA:

ossaVersion: "0.2.4"

agent:
  id: my-agent
  name: My Agent
  version: "1.0.0"
  role: worker

8.3 Validation

ossa validate agent.yml
ossa generate worker --name my-agent
buildkit ossa compliance --validate

9. Project Management

9.1 Required Labels

Type (one required): type::feature, type::bug, type::enhancement, type::documentation, type::refactor, type::security, type::task

Status (one required): status::needs-triage, status::ready-for-dev, status::in-progress, status::blocked, status::needs-review, status::completed

SemVer (one required): semver::minor, semver::patch

9.2 Milestone Format

v{major}.{minor}.{patch} — e.g., v0.1.0, v0.2.0

10. Safety

10.1 Blocked Commands

rm -rf /
rm -rf ~
rm -rf /*
dd if=/dev/zero of=/dev/sda
:(){ :|:& };:

10.2 Warning Commands

Require confirmation: rm -r, git push --force, git reset --hard, chmod -R 777, sudo

10.3 Irreversible Actions - STOP AND VERIFY

⚠️ CRITICAL: See Critical Warnings for full details on disasters that have occurred.

npm Publishing (versions are PERMANENT - cannot be reused after publish): 1. Run all tests: npm test 2. Run build: npm run build 3. Publish to RC first: npm publish --tag rc 4. Test RC in separate project 5. Get explicit user approval 6. Only then: npm dist-tag add @scope/package@version latest

GitLab Issue Closing: 1. Read ALL comments on the issue 2. Look for completion markers ("✅ COMPLETED", "Merged in MR") 3. Verify linked MRs are MERGED (not just created) 4. Ask user if uncertain

Milestone Operations: 1. Understand why milestone is changing (release vs abandon vs delay) 2. Verify issue completion states before moving 3. Ask before bulk moves: "Moving {count} issues - confirm?"

11. Compliance Checklists

Before Every Commit

• [ ] Working in worktree directory
• [ ] Branch name follows convention
• [ ] Commit message is conventional
• [ ] Tests written and passing
• [ ] Code formatted
• [ ] No lint errors

Before Every MR

• [ ] Pipeline passing
• [ ] Coverage thresholds met
• [ ] Milestone assigned
• [ ] Labels applied
• [ ] Linked to issue

This document is the authoritative source for AI agent behavior in the LLM Platform ecosystem.