Devac

DevAC Plugin for Claude Code

DevAC plugin providing Analytics Layer skills and Workflow commands for code analysis and development workflows.

How Plugin Loading Works

Understanding how Claude Code loads plugins is important to avoid confusion:

Loading Methods (In Order of Preference)

Method	Command Format	When to Use
Install via Marketplace	/devac:commit	Recommended - works globally in any project
Marketplace (vivief repo)	/commit	Working inside the vivief repository
--plugin-dir	/devac:commit	Development/testing of the plugin

What "Project Scope" Means

When using Claude Code in a multi-repo workspace (like ~/ws/ containing multiple repositories):

• Project = the directory where you launched Claude Code
• If you run claude from ~/ws/vivief/, the plugin loads for that session
• If you run claude from ~/ws/ (parent directory), the plugin loads if vivief's marketplace is detected
• Other sibling repositories (~/ws/other-repo/) don't automatically get the plugin

Important: The plugin scope is tied to the Claude Code session, not individual repositories within your workspace.

---

Setup Guide

Option 1: Install via Marketplace (Recommended)

The DevAC plugin is published to GitHub and can be installed globally via Claude Code's plugin system. This works in any project without needing the vivief repository.

# Add the vivief marketplace (one-time setup)
claude plugin marketplace add pietgk/vivief

# Install the DevAC plugin
claude plugin install devac@vivief

Verify installation:

claude plugin marketplace list
# Should show: vivief - Source: GitHub (pietgk/vivief)

After installation, commands are available with the devac: namespace prefix:

• /devac:commit - Full commit workflow
• /devac:ship - Commit, push, and create PR
• /devac:start-issue - Start work on an issue
• etc.

Option 2: Working Inside the Vivief Repository

If you're a vivief developer, the plugin loads automatically via the repository's marketplace configuration.

Usage:

cd ~/ws/vivief
claude

Commands are available without namespace prefix:

• /commit, /ship, /start-issue, etc.

Option 3: Development/Testing (--plugin-dir)

For testing plugin changes during development:

claude --plugin-dir /path/to/vivief/plugins/devac

Commands will be namespaced as /devac:commit, /devac:ship, etc.

---

Quick Reference: Command Names

If Plugin Loaded Via...	Command Format	Example
Install via Marketplace	/devac:command	/devac:commit
Marketplace (inside vivief)	/command	/commit
--plugin-dir	/devac:command	/devac:commit

---

Conceptual Model

┌──────────────────────────────────────────┬─────────────────────┐
│      CLI (devac, devac-worktree)         │   MCP (devac-mcp)   │
│  Preferred - low context overhead        │  Alternative access │
└──────────────────────────────────────────┴─────────────────────┘
         │                                          │
         └────────────────────┬─────────────────────┘
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                    SHARED CORE (devac-core)                     │
└────────────────────────────────────────────────────────────────┘

Key Principles:

• CLI is preferred - Skills invoke devac commands via Bash for lower context overhead
• CLI and MCP share implementation - Both import from devac-core and behave identically
• MCP is optional - Skills work without MCP server running

---

What's Included

Skills (Auto-Invoked)

Skills activate automatically based on your conversation:

Skill	Triggers On	Description
code-analysis	"analyze code", "find functions"	Analyze code structure and symbols
codebase-navigation	"find where X is defined"	Navigate and locate code
define-effects	"define effects", "map effects"	Create and maintain effect mappings
diagnostics-fix	"fix errors", "fix diagnostics"	Fix validation errors and warnings
diagnostics-triage	"what needs fixing"	Triage errors and warnings
effects-architecture	"document architecture", "C4 diagram"	Generate architecture documentation from effects
explain-package	"explain this package", "document package"	Generate human-readable package documentation
impact-analysis	"what will this affect"	Determine change impact and dependencies
multi-repo-context	"cross-repo", "workspace"	Work across multiple repositories
validate-architecture	"validate architecture", "check constraints"	Validate architecture rules and constraints

Commands (User-Invoked)

Command	Description
/commit	Full commit workflow with changeset/ADR checks
/ship	Commit, push, and create PR
/start-issue	Start work on a GitHub issue (supports worktree creation)
/issue	Create a new GitHub issue
/prepare-commit	Prepare commit message (review before committing)
/draft-commit	Draft commit message only
/prepare-pr	Prepare PR description
/draft-changeset	Draft changeset for release
/draft-adr	Draft architecture decision record
/devac-status	Query status across all Four Pillars
/plans	Manage plan files (list, read, create)
/setup	Guided setup wizard for DevAC
/validate-architecture	Validate architecture constraints

Note: Commands shown without namespace. If installed via marketplace or using --plugin-dir, prefix with devac: (e.g., /devac:commit).

---

Prerequisites

1. DevAC CLI installed

   npm install -g @pietgk/devac-cli
   

2. Hub initialized (for multi-repo features)

   devac sync
   

3. Repositories analyzed

   cd your-repo
   devac sync
   

---

CLI Commands Used by Skills

Skills invoke CLI commands for all DevAC operations:

# Code analysis
devac query symbol UserService
devac file-symbols src/auth/

# Impact analysis
devac query affected src/core/auth.ts
devac query deps src/services/user.ts

# Diagnostics
devac status --diagnostics
devac status --diagnostics --severity error

# Multi-repo
devac status --hub
devac query repos

# Effects documentation
devac effects init -p <package>
devac effects verify -p <package>
devac effects sync -p <package>
devac effects list -p <package>

---

MCP Integration (Alternative)

An MCP server configuration is included for devac-mcp. MCP provides the same functionality with higher context overhead:

Query Tools:

• query_symbol - Find symbols by name
• query_file - Get symbols in a file
• query_deps - Get symbol dependencies
• query_dependents - Get reverse dependencies
• query_affected - Get affected files
• query_call_graph - Get function call graphs
• query_sql - Query the Seeds database
• query_repos - List connected repositories

Status Tools:

• status - Get workspace status
• status_diagnostics - Get validation errors
• status_diagnostics_summary - Get diagnostics overview
• status_all_diagnostics - Get all diagnostics (unified)

Note: CLI is preferred. MCP is useful when you have it configured but is not required.

---

Usage Examples

Skills (Just Ask)

"What functions are in the auth module?"
"What will be affected if I change UserService?"
"What TypeScript errors need fixing?"
"Show me the workspace status"

Commands (Explicit Invocation)

/start-issue 123
/commit
/ship

---

Troubleshooting

Commands Not Found

Symptom: /commit or /devac:commit doesn't work

Check:

1. Installed via marketplace? → Commands are /devac:commit
2. Inside the vivief directory? → Commands are /commit (no namespace)
3. Using --plugin-dir? → Commands are /devac:commit
4. Plugin not loaded? → Run claude plugin list to check, then /help to see available commands

Skills Not Activating

Check:

1. Is DevAC CLI installed? → devac --version
2. Is the repository analyzed? → devac status --hub

Plugin Not Loading

Check:

1. Verify marketplace.json exists: cat .claude-plugin/marketplace.json
2. Check plugin structure: ls plugins/devac/
3. Restart Claude Code after changes

---

Learn More

• Vivief Workflow Guide - Complete development workflow
• CLI Reference - DevAC CLI commands
• MCP Server Reference - MCP integration