vale-agentic

A Vale style package that helps you write more assertive, action-oriented language by identifying and suggesting alternatives to communal phrasing. Now with 167 comprehensive patterns (86 communal detections + 81 agentic alternatives) for maximum career impact.

What is Agentic Language?

Agentic language emphasizes personal agency, ownership, and direct action. Instead of using passive, communal, or uncertain phrasing, agentic language helps you communicate with confidence and clarity.

Examples of transformations:

• ❌ "I helped improve the system" → ✅ "I improved the system"
• ❌ "I'm a team player" → ✅ "I collaborate effectively"
• ❌ "I facilitated discussions" → ✅ "I led discussions"
• ❌ "I think maybe we should..." → ✅ "I recommend we..."

This is especially valuable for performance reviews, cover letters, and professional communications where clear ownership and impact matter.

Installation

❗ vale-agentic requires Vale >= 1.7.0. ❗

Method 1: Download from Releases (Recommended)

1. Download the latest release
2. Extract the archive
3. Copy the agentic directory to your Vale StylesPath

Method 2: Clone Repository

git clone https://github.com/HeyItsGilbert/vale-agentic.git
cp -r vale-agentic/agentic /path/to/your/styles/

Method 3: Git Submodule

cd your-project
git submodule add https://github.com/HeyItsGilbert/vale-agentic.git styles/vale-agentic
# Link or copy the agentic directory to your StylesPath

Configuration

Create or update your Vale configuration file (.vale.ini or _vale.ini):

# Basic configuration
StylesPath = styles
MinAlertLevel = suggestion

# Apply to markdown and text files
[*.{md,txt}]
BasedOnStyles = agentic

# For different file types
[*.rst]
BasedOnStyles = agentic

# Customize alert levels
[*.md]
BasedOnStyles = agentic
agentic.communal = warning
agentic.communal_alternative = suggestion

Examples

Before and After

Original text:

I improved feature X by doing Y. I am known as a team player in org. I enjoy
facilitating thoughtful discussions.

Vale output:

example.md:1:3:agentic.communal:Consider replacing 'improved'. It is communal vs agentic.
example.md:1:50:agentic.communal:Consider replacing 'team player'. It is communal vs agentic.  
example.md:2:14:agentic.communal_alternative:Consider using 'energetic' instead of 'thoughtful'

Revised text:

I enhanced feature X by implementing Y. I am known as a collaborative leader in the organization. I enjoy
leading energetic discussions.

Common Issues Caught

Communal Phrase	Issue	Suggested Alternative
"I helped improve..."	Diminishes ownership	"I improved..."
"team player"	Vague, overused	"collaborative", "supportive"
"maybe we should..."	Lacks conviction	"I recommend...", "We should..."
"managed to..."	Implies difficulty	"successfully...", "achieved..."
"facilitated"	Passive role	"led", "directed", "guided"

Usage

Command Line

# Check a single file
vale example.md

# Check all markdown files
vale *.md

# Get JSON output
vale --output=JSON example.md

# Focus on agentic rules only
vale --filter='agentic.*' example.md

Integration with Editors

VS Code: Install the Vale VS Code extension

Vim/Neovim: Use with ALE or coc-vale

Emacs: Use flycheck-vale

Rules Reference

agentic.communal

Identifies words and phrases that diminish personal agency (86 patterns):

• Passive constructions: tried to, attempted to, managed to, was able to, happened to
• Hedge words: maybe, perhaps, possibly, I think, I believe, I guess
• Minimizing language: just, simply, only, merely, somehow, kind of, sort of
• Self-deprecating: lucky, fortunate, by chance, accidentally, surprisingly
• Apologetic: sorry, unfortunately, sadly, I'm afraid, wish I could
• Generic descriptors: nice, friendly, sweet, accommodating, understanding
• Permission-seeking: I hope, would it be okay, if possible, would you mind
• Collaborative downplay: team effort, group achievement, shared responsibility

agentic.communal_alternative

Suggests stronger alternatives (81 mappings):

• Agency: tried to → executed, attempted to → completed, managed to → accomplished
• Confidence: I think → I recommend, perhaps → recommend, maybe → suggest
• Ownership: team effort → I coordinated, group achievement → I contributed to
• Professionalism: nice → professional, accommodating → adaptable, understanding → empathetic
• Directness: unfortunately → however, sorry → recommend, I hope → I recommend
• Strength: lucky → strategic, by chance → through analysis, simply → directly

Troubleshooting

Vale not finding the style:

• Ensure the agentic directory is in your StylesPath
• Check that .vale.ini is in your project root or home directory
• Verify Vale version >= 1.7.0 with vale --version

Too many/few alerts:

• Adjust MinAlertLevel (suggestion, warning, error)
• Customize individual rule levels in your config
• Use --filter to focus on specific rules

Contributing

Found a communal phrase we missed? Have a better alternative suggestion?

1. Fork the repository
2. Add test cases in fixtures/
3. Update the appropriate .yml rule file
4. Submit a pull request

Related Projects

• Vale - The extensible linter this style is built for
• alex - Catch insensitive, inconsiderate writing
• write-good - Naive linter for English prose

License

MIT