AI Dev OS Plugin — Claude Code — Operation Guide

Prerequisites
Installation
Initial Setup
Daily Workflow
Periodic Maintenance
Team Onboarding
Language Policy
CI Integration
Troubleshooting

1. Prerequisites

Claude Code >= 1.0.0
AI Dev OS layer files (L1-L3) set up in your project (see templates: TypeScript / Python)

2. Installation

Option A: CLI (Recommended)

The fastest way to set up AI Dev OS with Claude Code:

npx ai-dev-os init --rules typescript --plugin claude-code

This automatically adds submodules, copies CLAUDE.md template, and merges hooks. See AI Dev OS CLI for all options.

Option B: Git Submodule

Add as a submodule to keep AI Dev OS updates separate from your project:

git submodule add https://github.com/yunbow/ai-dev-os-plugin-claude-code.git .claude/plugins/ai-dev-os

Option B: Direct Clone

git clone https://github.com/yunbow/ai-dev-os-plugin-claude-code.git
cp -r ai-dev-os-plugin-claude-code/skills/ .claude/skills/
cp -r ai-dev-os-plugin-claude-code/agents/ .claude/agents/

Hook Setup

Copy the hook definitions from hooks/hooks.json into your project's .claude/settings.json:

{
  "permissions": { ... },
  "hooks": {
    "PreToolUse": [ ... ],
    "PostToolUse": [ ... ],
    "UserPromptSubmit": [ ... ]
  }
}

Refer to hooks/hooks.json for the full hook configuration.

Hook Merge Guide

If your .claude/settings.json already exists and contains other settings, merge the hooks manually:

Option A: Manual merge

Open hooks/hooks.json and your .claude/settings.json side by side
Copy each array (PreToolUse, PostToolUse, UserPromptSubmit) from hooks/hooks.json
If your settings.json already has a hooks key, append the entries to each existing array
If your settings.json does not have a hooks key, add the entire hooks object

Option B: Using jq (Unix/macOS)

jq -s '.[0] * {hooks: (.[0].hooks // {} | to_entries + (.[1].hooks | to_entries) | group_by(.key) | map({(.[0].key): [.[] | .value[]] }) | add)}' .claude/settings.json hooks/hooks.json > .claude/settings.merged.json
mv .claude/settings.merged.json .claude/settings.json

Verification: After merging, confirm that your settings.json contains PreToolUse, PostToolUse, and UserPromptSubmit arrays under the hooks key.

3. Initial Setup

Run the Setup Wizard

/ai-dev-os-init [tech-stack]

Example:

/ai-dev-os-init nextjs

The wizard will:

Ask about your tech stack, project scale, and existing rule files
Detect and import existing rules (.cursorrules, CLAUDE.md, .eslintrc)
Generate the 4-layer directory structure
Create a CLAUDE.md with guideline references and Specificity Cascade
Optionally set up git submodule isolation

Verify Setup

After initialization, confirm the structure:

ai-dev-os/
├── 01_philosophy/
├── 02_decision-criteria/
├── 03_guidelines/
│   ├── common/
│   └── frameworks/
└── 04_ai-frames/

4. Daily Workflow

4.1 Planning Before Implementation

For non-trivial changes, create a guideline-aware plan first:

/ai-dev-os-plan Add user authentication with JWT

This will:

Analyze your request and identify affected files
Map files to relevant AI Dev OS guidelines
Generate a checklist of applicable rules
Present the plan for your approval before any code is written

The hook will also suggest /ai-dev-os-plan when it detects implementation-related prompts.

4.2 Creating Tickets Instead of Implementing

When you want to defer implementation — e.g., for team assignment or backlog management — create a ticket instead:

/ai-dev-os-ticket Add user authentication with JWT

This will:

Perform the same analysis as /ai-dev-os-plan (affected files, guideline mapping, checklist)
Ask where to create the ticket (if not configured in CLAUDE.md):
- Local file: saves as TICKET-001-add-user-auth.md in the specified directory
- GitHub Issue: creates an issue via gh issue create
Present a preview for your approval
Create the ticket — without writing any code

To pre-configure the ticket destination, add to your project's CLAUDE.md:

## Ticket Settings
- output: file
- path: docs/tickets/phase1

Or for GitHub Issues:

## Ticket Settings
- output: github-issue

4.3 Writing Code

Write code as usual. The hooks will automatically:

Check guideline compliance on every Write/Edit operation
Warn about dependency rule violations when editing L1-L2 files
Remind you to run compliance checks before committing

4.4 Before Committing

Run the compliance check:

/ai-dev-os-check

This will:

Parse CLAUDE.md to find applicable guidelines
Get changed files from git diff
Map files to relevant guidelines
Check compliance and output a report

4.5 After Code Review

When you fix AI-generated code during review, extract new rules:

/ai-dev-os-extract [file-path]

This will:

Analyze the diff to identify why changes were made
Generate rule candidates in MUST / MUST NOT format
Propose target guideline files and L2 principle links
Add rules to guidelines upon approval

4.6 Understanding Rules

When a team member questions a rule:

/ai-dev-os-why [rule-or-guideline]

Example:

/ai-dev-os-why "why is any type prohibited?"

5. Periodic Maintenance

Monthly: Health Audit

/ai-dev-os-audit

Checks:

Dependency rule compliance (no tool-specific terms in L1, no framework details in L2)
Freshness (L1: 5yr, L2: 3yr, L3: 12mo, L4: 4mo)
Traceability (L3→L2 links, orphaned rules)
Coverage (guidelines for all file patterns)
Consistency (no contradicting rules)

Quarterly: SECI Spiral Evolution

/ai-dev-os-evolve

Analyzes recent commits and review patterns to propose updates to L1 philosophy and L2 principles. This is the "knowledge spiral" — extracting tacit knowledge from daily practice into explicit principles.

Weekly/Monthly: Compliance Report

/ai-dev-os-report 1w
/ai-dev-os-report 1m

Generates a summary report suitable for team meetings or stakeholder updates.

6. Team Onboarding

For New Team Members

Read ai-dev-os/01_philosophy/core-values.md (5 min)
Skim ai-dev-os/02_decision-criteria/ (10 min)
Run /ai-dev-os-why for any rules that seem unclear
Start coding — hooks will guide compliance automatically

For Teams Adopting AI Dev OS

Run /ai-dev-os-init on the project
Start with the starter template (L3 only)
Use /ai-dev-os-extract after each code review session
After 2-4 weeks, run /ai-dev-os-audit to identify gaps
Gradually build L1-L2 through /ai-dev-os-evolve

7. Language Policy

All plugin source files (skills, agents, hooks, templates) are maintained in English. This ensures optimal LLM accuracy and broad accessibility. Translated documentation is provided under docs/i18n/ for reference, but English remains the single source of truth.

8. CI Integration

Hooks provide real-time advisory guidance but operate only within the AI coding tool. They do not enforce compliance at the repository level. For team-wide enforcement, integrate AI Dev OS checks into your CI pipeline.

GitHub Actions Example

name: AI Dev OS Compliance
on: [pull_request]

jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Check guideline compliance
        run: |
          # Option 1: Run markdownlint on guideline files
          npx markdownlint-cli docs/ai-dev-os/**/*.md

          # Option 2: Custom compliance script
          # Parse ai-dev-os-scan JSON output and fail on violations
          # python scripts/check-compliance.py --strict

Enforcement Levels

Level	Behavior	Recommended For
Advisory	Hooks warn during development, CI reports violations but does not block	Solo developers, small teams
Warning	CI posts violation comments on PRs but allows merge	Teams adopting AI Dev OS gradually
Blocking	CI fails on critical violations (security, auth)	Established teams with mature rules

Start with advisory level and escalate as your rules mature ([draft] → [proven]).

9. Troubleshooting

Hooks not triggering

Verify hooks are in .claude/settings.json (not hooks/hooks.json directly)
Check that jq is installed (jq --version)
On Windows, ensure bash is available in PATH

Skills not found

Verify skill files are in .claude/skills/ directory
Each skill must have a SKILL.md file with valid YAML frontmatter
Run ls .claude/skills/ to confirm

False positive violations

If a check is too strict, edit the corresponding guideline in 03_guidelines/
Use /ai-dev-os-why to understand the rule's rationale before removing it
Consider relaxing the rule rather than removing it entirely

Performance

Hook checks run on every Write/Edit — if too slow, reduce guideline scope
Use context: fork skills (extract, audit, evolve) for heavy operations
Sub-agents run in isolated context to avoid polluting your main session

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

AI Dev OS Plugin — Claude Code — Operation Guide

Table of Contents

1. Prerequisites

2. Installation

Option A: CLI (Recommended)

Option B: Git Submodule

Option B: Direct Clone

Hook Setup

Hook Merge Guide

Option A: Manual merge

Option B: Using jq (Unix/macOS)

3. Initial Setup

Run the Setup Wizard

Verify Setup

4. Daily Workflow

4.1 Planning Before Implementation

4.2 Creating Tickets Instead of Implementing

4.3 Writing Code

4.4 Before Committing

4.5 After Code Review

4.6 Understanding Rules

5. Periodic Maintenance

Monthly: Health Audit

Quarterly: SECI Spiral Evolution

Weekly/Monthly: Compliance Report

6. Team Onboarding

For New Team Members

For Teams Adopting AI Dev OS

7. Language Policy

8. CI Integration

GitHub Actions Example

Enforcement Levels

9. Troubleshooting

Hooks not triggering

Skills not found

False positive violations

Performance

FilesExpand file tree

operation-guide.md

Latest commit

History

operation-guide.md

File metadata and controls

AI Dev OS Plugin — Claude Code — Operation Guide

Table of Contents

1. Prerequisites

2. Installation

Option A: CLI (Recommended)

Option B: Git Submodule

Option B: Direct Clone

Hook Setup

Hook Merge Guide

Option A: Manual merge

Option B: Using jq (Unix/macOS)

3. Initial Setup

Run the Setup Wizard

Verify Setup

4. Daily Workflow

4.1 Planning Before Implementation

4.2 Creating Tickets Instead of Implementing

4.3 Writing Code

4.4 Before Committing

4.5 After Code Review

4.6 Understanding Rules

5. Periodic Maintenance

Monthly: Health Audit

Quarterly: SECI Spiral Evolution

Weekly/Monthly: Compliance Report

6. Team Onboarding

For New Team Members

For Teams Adopting AI Dev OS

7. Language Policy

8. CI Integration

GitHub Actions Example

Enforcement Levels

9. Troubleshooting

Hooks not triggering

Skills not found

False positive violations

Performance