@-Mention Conventions

Display AIWG @-mention naming conventions and placement rules.

Usage

/mention-conventions                  # Show all conventions
/mention-conventions --section naming # Show naming patterns only
/mention-conventions --section placement # Show placement rules only

Naming Patterns

Requirements

@.aiwg/requirements/UC-{NNN}-{slug}.md        # Use cases (UC-001-user-auth.md)
@.aiwg/requirements/NFR-{CAT}-{NNN}.md        # Non-functional (NFR-SEC-001.md)
@.aiwg/requirements/user-stories.md           # User story collection

Categories for NFRs:

• SEC

  - Security

• PERF

  - Performance

• SCAL

  - Scalability

• AVAIL

  - Availability

• MAINT

  - Maintainability

• USAB

  - Usability

Architecture

@.aiwg/architecture/adrs/ADR-{NNN}-{slug}.md  # Decision records (ADR-005-jwt-strategy.md)
@.aiwg/architecture/components/{name}.md      # Component specs
@.aiwg/architecture/software-architecture-doc.md  # Main SAD
@.aiwg/architecture/api-contract.md           # API specifications

Security

@.aiwg/security/threat-model.md               # Main threat model
@.aiwg/security/TM-{NNN}.md                   # Individual threats (TM-001.md)
@.aiwg/security/controls/{control-id}.md      # Security controls (authn-001.md)

Testing

@.aiwg/testing/test-plan.md                   # Master test plan
@.aiwg/testing/test-cases/TC-{NNN}.md         # Individual test cases
@.aiwg/testing/test-results/{run-id}.md       # Test run results

Code References

@$AIWG_ROOT/src/{path/to/file}                           # Source files
@test/{path/to/file}                          # Test files
@lib/{path/to/file}                           # Library files
@$AIWG_ROOT/docs/{path/to/file}                          # Documentation

Placement Rules

In Code Files

Place @-mentions in file header docblock:

/**
 * @file Authentication Service
 * @implements @.aiwg/requirements/UC-003-user-auth.md
 * @architecture @.aiwg/architecture/adrs/ADR-005-jwt-strategy.md
 * @security @.aiwg/security/controls/authn-001.md
 * @tests @test/integration/auth.test.ts
 */
export class AuthService {
  // Implementation
}

In Python Files

"""
Authentication Service

@implements: @.aiwg/requirements/UC-003-user-auth.md
@architecture: @.aiwg/architecture/adrs/ADR-005-jwt-strategy.md
@security: @.aiwg/security/controls/authn-001.md
@tests: @test/integration/test_auth.py
"""

In Markdown Documents

Add a References section:

## References

- @.aiwg/requirements/user-stories.md - Functional requirements basis
- @.aiwg/architecture/software-architecture-doc.md - Architecture context
- @.aiwg/security/threat-model.md - Security considerations

In Inline Comments

For specific code sections:

// Per @.aiwg/security/controls/authn-001.md - validate token expiry
if (token.exp < Date.now()) {
  throw new AuthError('Token expired');
}

ID Format Rules

Type	Format	Example
Use Case	UC-NNN	UC-001, UC-042
NFR	NFR-CAT-NNN	NFR-SEC-001, NFR-PERF-002
ADR	ADR-NNN	ADR-001, ADR-015
Threat	TM-NNN	TM-001, TM-023
Test Case	TC-NNN	TC-001, TC-150

Rules:

• Always use 3-digit zero-padded numbers
• Use lowercase for paths
• Use hyphens for slugs (not underscores)

Best Practices

1. Be Specific: Reference exact documents, not directories
2. Keep Current: Update @-mentions when files move
3. Validate Often: Run

   /mention-validate

   before commits
4. Lint Style: Run

   /mention-lint --fix

   to normalize
5. Generate Reports: Use

   /mention-report

   for traceability audits

CLI Equivalent

aiwg mention-conventions

Related Commands

• /mention-wire

  - Add @-mentions automatically

• /mention-lint

  - Validate style conventions

• /mention-validate

  - Check all @-mentions resolve

Display conventions: $ARGUMENTS