Permissions Manager

Quick Reference
Intent Classification Decision Tree
Core Detection Logic
Resource Loading Policy
Safety Rules
Token Budget Management
Error Handling
Skill Integration Points
Success Criteria Checklist
Quick Start Examples

Quick Reference

Purpose: Auto-configure Claude Code permissions via natural language Token Budget: T1(100) + T2(2,500) + T3(1,500-3,000 per workflow) Architecture: Progressive Disclosure (3-tier) - Load only what's needed

Intent Classification Decision Tree

Step 1: Detect Request Type

Parse user message for patterns:

CLI Tool Request - Indicators:

Keywords: "enable", "allow", "configure" + tool name
Tool names: git, gcloud, aws, kubectl, docker, npm, pip, maven, gradle, cargo, helm, terraform, pulumi, ansible
Modes: "read", "write", "read-only", "commits", "pushes"
Route to: guides/workflows/cli-tool-workflow.md

File Pattern Request - Indicators:

Keywords: "make editable", "edit", "write" + file type/pattern
Patterns: "**.md", "TypeScript files", "src/", "docs folder"
Route to: guides/workflows/file-pattern-workflow.md

Project Type Request - Indicators:

Keywords: "this is a [language] project", "setup", "project"
Languages: Rust, Java, TypeScript, Python, Go, Ruby, PHP, C#, C++, Swift
Route to: guides/workflows/project-setup-workflow.md

Profile Request - Indicators:

Keywords: "apply profile", "use profile" + profile name
Profiles: read-only, development, ci-cd, production, documentation, code-review, testing
Route to: guides/workflows/profile-application-workflow.md

Validation/Troubleshooting - Indicators:

Keywords: "validate", "check", "troubleshoot", "not working"
Route to: guides/workflows/validation-workflow.md

Backup/Restore - Indicators:

Keywords: "backup", "restore", "rollback", "undo"
Route to: guides/workflows/backup-restore-workflow.md

Step 2: Load Appropriate Workflow

CRITICAL: Load ONLY the workflow guide needed. Do NOT load multiple guides.

Request Type	Workflow File	Token Cost
CLI Tool	`guides/workflows/cli-tool-workflow.md`	+1,500
File Pattern	`guides/workflows/file-pattern-workflow.md`	+1,200
Project Type	`guides/workflows/project-setup-workflow.md`	+1,800
Profile	`guides/workflows/profile-application-workflow.md`	+1,000
Validation	`guides/workflows/validation-workflow.md`	+1,200
Backup/Restore	`guides/workflows/backup-restore-workflow.md`	+750
Unknown Tool	`guides/workflows/research-workflow.md`	+2,000

Core Detection Logic

CLI Tool Recognition

Known Tools (check against references/cli_commands.json):

Version Control: git
Cloud: gcloud, aws, az
Containers: docker, kubectl, helm
Build: npm, pip, maven, gradle, cargo, go, yarn, bundle, composer
Infrastructure: terraform, pulumi, ansible

Mode Detection:

Contains "read", "list", "show", "describe" -> READ mode (safer default)
Contains "write", "push", "commit", "deploy", "publish" -> WRITE mode
No mode -> Default to READ

Tool Lookup:

Check if tool in references/cli_commands.json (use grep)
If found -> Extract commands for detected mode
If NOT found -> Route to research workflow

Project Type Detection

Auto-Detection (via file scanning):

Cargo.toml                      -> Rust
pom.xml                         -> Java Maven
build.gradle*                   -> Java Gradle
package.json + tsconfig.json    -> TypeScript
package.json (alone)            -> JavaScript
pyproject.toml | setup.py       -> Python
go.mod                          -> Go
Gemfile                         -> Ruby
composer.json                   -> PHP
*.csproj | *.sln                -> C#
CMakeLists.txt                  -> C++
Package.swift                   -> Swift

Detection Method: Run scripts/detect_project.py or scan for indicator files

Profile Recognition

Available Profiles (from assets/permission_profiles.json):

read-only - Code review, security audit
development - Active development (most common)
ci-cd - Continuous integration
production - Monitoring only
documentation - Docs writing
code-review - PR review
testing - TDD workflow

Resource Loading Policy - CRITICAL

NEVER load resources proactively or "just in case"

Loading Workflow Guides

DO: Load specific workflow when decision tree routes to it

Read guides/workflows/{workflow-name}.md

DON'T: Load all guides upfront or multiple guides

Loading Reference Data - Surgical Only

CLI Commands (one tool only):

grep -A 25 '"git"' references/cli_commands.json
# Token cost: ~150 tokens (vs 2,650 for full file)

Project Templates (one language only):

jq '.rust' references/project_templates.json
# Token cost: ~200 tokens (vs 1,955 for full file)

Security Patterns (one level only):

jq '.recommended_deny_set.standard' references/security_patterns.json
# Token cost: ~100 tokens (vs 805 for full file)

Permission Profiles (one profile only):

jq '.development' assets/permission_profiles.json
# Token cost: ~200 tokens (vs 1,240 for full file)

Executing Scripts

ONLY execute when workflow instructs:

detect_project.py - When project type ambiguous or need recommendations
apply_permissions.py - When all rules gathered, handles backup/validation/writing
validate_config.py - When user requests validation or troubleshooting

Safety Rules - Always Apply

Every permission operation MUST:

Load security patterns: jq '.recommended_deny_set.standard' references/security_patterns.json
Apply minimum deny rules: See references/security_patterns.json#recommended_deny_set.standard for full list (14 rules)
Create backup before any settings write (automatic via scripts/apply_permissions.py)
Validate syntax before applying (automatic via scripts/apply_permissions.py)

Token Budget Management

Budget Tiers:

Simple request (CLI tool): <5,000 tokens
Medium request (project setup): <7,000 tokens
Complex request (unknown tool): <10,000 tokens
Warning threshold: >10,000 tokens

Cost Optimization:

Use grep/jq for references (90% token savings)
Load only needed workflow guide
Execute scripts instead of explaining them
Avoid loading examples unless requested

See references/token_tracking_template.md for tracking template.

Error Handling

If workflow guide not found:

Proceed with best-effort inline logic
Inform user of missing guide
Suggest filing an issue

If reference file not found:

Attempt operation without reference
For unknown tools -> use web search
Warn user about limited functionality

If script execution fails:

Show error message to user
Suggest manual permission editing
Provide settings file location

If validation fails:

Report specific errors
Suggest fixes
Offer to restore from backup

Skill Integration Points

Other Skills (invoke when appropriate):

gemini skill: If user mentions "gemini CLI" and skill available

MCP Tools (priority order for research):

mcp__perplexity-ask__perplexity_ask (preferred)
mcp__brave-search__brave_web_search (fallback)
WebSearch (final fallback)

Success Criteria Checklist

Permission operation complete when:

Backup created (timestamped)
Permissions validated (syntax + conflicts)
Safety rules applied (deny patterns)
Settings written successfully
User informed of changes
Restart reminder provided

Quick Start Examples

Request	Route
Enable git (read-only)	`cli-tool-workflow.md`
Make markdown editable	`file-pattern-workflow.md`
Setup TypeScript project	`project-setup-workflow.md`
Apply development profile	`profile-application-workflow.md`

See guides/workflows/ for complete workflow documentation.

Workflow Pattern

Every request follows this pattern:

Classify intent using decision tree
Route to workflow based on detection
Load workflow guide from guides/workflows/
Follow workflow step-by-step
Load references surgically as needed
Execute scripts when required
Track token budget throughout
Complete operation per success criteria
Inform user of changes

Remember: Load only needed workflow, use grep/jq for references, execute scripts for heavy lifting, apply safety rules always.

End of Tier 2 (SKILL.md)

permissions-manager