2155 6767 F At Arch Plugin Scaffold Diagrams 6dd388b6

6767-f-AT-ARCH-plugin-scaffold-diagrams.md

Document Type: Architecture & Technical - Architecture (AT-ARCH) Document ID: 6767-f-AT-ARCH-plugin-scaffold-diagrams Title: Plugin Scaffold Diagrams (Enforceable) Version: 3.0.0 Status: CANONICAL (Enterprise-Only) Date: 2025-12-20 Companion To: 6767-c (Extensions Standard), 6767-d (Schema), 6767-e (Validation) Authority: Intent Solutions (Enterprise Marketplace) Normative Language: This document uses MUST / SHOULD / MAY

TRUTH INVARIANTS (ENTERPRISE MODE)

MODE: ENTERPRISE MODE ALWAYS ON. No "Anthropic-minimum" fallback. All fields marked "REQUIRED" are REQUIRED.

CORE RULES:

1. allowed-tools Format:

   • ✅ CORRECT: CSV string → allowed-tools: "Read,Write,Grep,Glob"
   • ❌ WRONG: YAML array → allowed-tools: [Read, Write, Grep]
   • Violation: CRITICAL ERROR (SKILL_022)

2. Bash Scoping:

   • ✅ CORRECT: Scoped → Bash(git:*), Bash(npm:*), Bash(python:*)
   • ❌ WRONG: Unscoped → Bash
   • Violation: CRITICAL ERROR (SKILL_024)

3. Path Portability:

   • ✅ CORRECT: ${CLAUDE_PLUGIN_ROOT}/... or {baseDir}/...
   • ❌ WRONG: /home/user/... or ~/...
   • Violation: CRITICAL ERROR (SKILL_103, SEC_005)

4. Naming Convention:

   • Pattern: ^[a-z0-9-]+$ (kebab-case only)
   • Max length: 64 chars
   • Reserved words: NO "claude" or "anthropic"
   • Violation: CRITICAL ERROR (NAMING_001, NAMING_002, NAMING_003)

5. Versioning:

   • Format: SemVer MAJOR.MINOR.PATCH (3 parts)
   • Example: 1.0.0, 2.3.1
   • Violation: CRITICAL ERROR (PLUGIN_012, SKILL_032)

6. Directory Structure:

   • .claude-plugin/ contains ONLY plugin.json
   • Component dirs (skills/, agents/, commands/) at plugin root, NOT inside .claude-plugin/
   • Violation: CRITICAL ERROR (DIR_002, DIR_005)

7. Security:

   • NO hardcoded secrets, API keys, .env files committed
   • Secrets via environment variables ONLY
   • Exemptions: ONLY tests/fixtures/** + known test patterns (EXAMPLE, DUMMY, test-)
   • Violation: CRITICAL ERROR (SEC_001, SEC_002, SEC_003, SEC_004)

8. Context Hygiene:

   • SKILL.md body ≤ 5,000 words / 500 lines / ~7,500 tokens
   • Heavy content in references/ directory (loaded on-demand)
   • Violation: HIGH ERROR (SKILL_100, SKILL_101)

9. Discoverability:

   • Description MUST include "Use when..." phrase
   • Description MUST include 2-6 trigger phrases
   • Violation: HIGH ERROR (SKILL_015, SKILL_016)

10. Required Fields (Enterprise):

    • Plugin: name, version, description, author (name + email), license, keywords
    • Skill: name, description, allowed-tools (CSV), version, author, license, tags
    • Violation: CRITICAL ERROR (various PLUGIN_*, SKILL_* codes)

VALIDATION:

• Validator runs in ENTERPRISE MODE ONLY
• CRITICAL/HIGH errors BLOCK PR merge
• Deterministic error codes (6767-d schema)

NO EXCEPTIONS: These rules apply to ALL plugins/skills, regardless of size or complexity.

1. Non-Negotiable Constraints (MUST)

1.1 Directory Structure Rules

1.2 Manifest Rules (plugin.json)

1.3 Documentation Rules

1.4 Portability Rules

1.5 Context Hygiene Rules

2. Canonical Directory Tree (Reference)

2.1 Minimal Plugin (Required Only)

my-plugin/                              ← Plugin root
├── .claude-plugin/                     ← REQUIRED: Metadata directory
│   └── plugin.json                     ← REQUIRED: ONLY file allowed here
├── README.md                           ← REQUIRED: Documentation
└── .claudeignore                       ← REQUIRED: Context exclusions

Validator Checks:

• DIR_001: .claude-plugin/ exists
• DIR_002: .claude-plugin/ contains ONLY plugin.json
• DIR_003: plugin.json exists at correct path
• PLUGIN_001-052: All plugin.json manifest checks

2.2 Full Plugin (All Optional Components)

my-plugin/                              ← Plugin root
├── .claude-plugin/                     ← REQUIRED: Metadata directory
│   └── plugin.json                     ← REQUIRED: ONLY file allowed
├── skills/                             ← OPTIONAL: Skill capabilities
│   ├── skill-1/
│   │   ├── SKILL.md                    ← Skill definition (frontmatter + body)
│   │   ├── scripts/                    ← Helper scripts for this skill
│   │   ├── references/                 ← Heavy docs (loaded on-demand)
│   │   └── assets/                     ← Templates, config files
│   └── skill-2/
│       └── SKILL.md
├── agents/                             ← OPTIONAL: Agent definitions
│   ├── specialist-1.md                 ← Agent definition (frontmatter + body)
│   └── specialist-2.md
├── commands/                           ← OPTIONAL: Slash commands
│   ├── command-1.md                    ← Command definition
│   └── command-2.md
├── hooks/                              ← OPTIONAL: Event hooks
│   └── hooks.json                      ← Hook configuration
├── scripts/                            ← OPTIONAL: Plugin-level scripts
│   ├── validate_standards.py
│   ├── setup.sh
│   └── ...
├── .mcp.json                           ← OPTIONAL: MCP server config
├── .claudeignore                       ← REQUIRED: Context exclusions
├── README.md                           ← REQUIRED: Documentation
└── 000-docs/                           ← OPTIONAL: Project docs (flat, NNN-CC-ABCD)
    ├── 001-DR-STND-doc-filing.md
    ├── 002-RA-ANLY-analysis.md
    └── 003-AA-AACR-action-report.md

Validator Checks (per component):

• Skills: SKILL_001-104 (frontmatter, body, security, naming)
• Agents: AGENT_001-021 (frontmatter, naming)
• Security: SEC_001-006 (secrets, paths, Bash scoping)
• Naming: NAMING_001-005 (kebab-case, reserved words, max length)

3. Diagrams (Normative + Annotated)

3.1 Plugin Anatomy Tree (Allowed/Forbidden Callouts)

See diagram: 6767-f-AT-DIAG-plugin-anatomy-1.mmd (PNG version)

Diagram Node → Validator Mapping:

3.2 Router → Skill → Script Control Loop

See diagram: 6767-f-AT-DIAG-router-skill-script-2.mmd (PNG version)

Diagram Step → Validator Mapping:

3.3 Path Resolution Diagram (Portable vs Broken)

See diagram: 6767-f-AT-DIAG-path-resolution-3.mmd (PNG version)

Diagram Path → Validator Mapping:

4. Enforcement Rules (Validator Checks)

4.1 Manifest Validation (plugin.json)

Check Category: PLUGIN_*

4.2 Directory Structure Validation

Check Category: DIR_*

4.3 Path Validation

Check Category: SEC_*

4.4 Document Filing Validation (if 000-docs/ present)

Check Category: DOC_*

4.5 CI Workflow Validation (Recommended)

Check Category: (Future: CI_*)

5. Examples (Good vs Bad)

5.1 Good plugin.json (Enterprise Compliant)

{
  "name": "analytics-toolkit",
  "version": "1.2.3",
  "description": "Advanced analytics and visualization tools for data-driven insights.",
  "author": {
    "name": "Analytics Team",
    "email": "analytics@example.com"
  },
  "license": "MIT",
  "keywords": ["analytics", "visualization", "data"],
  "homepage": "https://docs.example.com/analytics",
  "repository": "https://github.com/example/analytics-toolkit",
  "skills": ["./skills/data-analysis/"],
  "mcpServers": {
    "data-server": {
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/server.py"]
    }
  }
}

Validator Result: ✅ PASS (all enterprise requirements met)

Passing Checks:

• ✅ PLUGIN_003: name is kebab-case
• ✅ PLUGIN_005: name ≤64 chars (18 chars)
• ✅ PLUGIN_006: no reserved words
• ✅ PLUGIN_012: version is SemVer (3 parts)
• ✅ PLUGIN_032: author has name + email
• ✅ PLUGIN_051-052: keywords present (3 items)
• ✅ SEC_005: paths use ${CLAUDE_PLUGIN_ROOT}

5.2 Bad plugin.json (Multiple Violations)

{
  "name": "Claude_Analytics_Plugin",
  "version": "1.0",
  "description": "Tool",
  "author": "Analytics Team",
  "keywords": []
}

Validator Result: ❌ FAIL (7 CRITICAL errors)

Failing Checks:

1. ❌ PLUGIN_003: name must be kebab-case (found: Claude_Analytics_Plugin)

   • Expected: ^[a-z0-9-]+$
   • Actual: Contains uppercase + underscores
   • Fix: Change to claude-analytics-plugin or analytics-plugin

2. ❌ PLUGIN_006: name contains reserved word "claude"

   • Expected: No "claude" or "anthropic" in name
   • Actual: Starts with "Claude"
   • Fix: Remove "Claude_" prefix

3. ❌ PLUGIN_012: version must be SemVer MAJOR.MINOR.PATCH

   • Expected: ^\d+\.\d+\.\d+$
   • Actual: 1.0 (missing PATCH)
   • Fix: Change to 1.0.0

4. ❌ PLUGIN_032: author must be object with name + email

   • Expected: {"name": "...", "email": "..."}
   • Actual: Plain string "Analytics Team"
   • Fix: Change to {"name": "Analytics Team", "email": "analytics@example.com"}

5. ❌ PLUGIN_041: license field missing

   • Expected: String field "license"
   • Actual: Not present
   • Fix: Add "license": "MIT"

6. ❌ PLUGIN_052: keywords array is empty

   • Expected: ≥1 item
   • Actual: [] (0 items)
   • Fix: Add keywords: ["analytics", "data"]

6. Common Failure Modes + Recovery

6.1 "Command not found" due to wrong paths

Symptom:

Error: python: command not found
File: ${CLAUDE_PLUGIN_ROOT}/bin/server.py

Cause: Script path is correct but script is not executable OR dependencies not installed.

Recovery:

1. Make script executable:

   chmod +x bin/server.py
   

2. Verify shebang:

   #!/usr/bin/env python3
   

3. Install dependencies:

   cd ${CLAUDE_PLUGIN_ROOT}
   pip install -r requirements.txt
   

4. Test manually:

   cd /path/to/plugin
   python bin/server.py
   

Validator Check: (Future: EXEC_001 - verify scripts are executable)

6.2 "Permission denied" from parent dir access

Symptom:

PermissionError: [Errno 13] Permission denied: '/home/jeremy/projects/../../etc/passwd'

Cause: Script uses path traversal (../) to access parent directories.

Root Cause: Violates SEC_005 (path traversal forbidden).

Recovery:

1. Identify violating path:

   grep -r '\.\./\.\.' .
   

2. Fix paths (use ${CLAUDE_PLUGIN_ROOT} instead):

   # ❌ BAD
   config_path = "../../config/settings.json"
   
   # ✅ GOOD
   import os
   plugin_root = os.getenv("CLAUDE_PLUGIN_ROOT")
   config_path = os.path.join(plugin_root, "config/settings.json")
   

3. Re-validate:

   python scripts/validate_standards.py --plugin-root .
   

Validator Check: SEC_005 catches .. in paths

6.3 "Skill not activating" due to generic description

Symptom: Skill exists but Claude doesn't activate it when user requests related functionality.

Cause: Description is too generic; lacks "Use when..." clause or trigger phrases.

Example (Bad):

description: "Data processing tool"

Why it fails:

• No "Use when..." clause
• No trigger phrases
• Too vague (what kind of data? what processing?)

Recovery:

1. Add "Use when" clause:

   description: "Process CSV files with statistical analysis and generate reports. Use when user uploads CSV data or requests statistical summaries, trend analysis, or data visualization. Trigger with 'analyze csv', 'process data file', or 'generate statistics'."
   

2. Include specific scenarios:

   • "when user uploads CSV"
   • "when user requests statistical summaries"

3. Add trigger phrases (quoted recommended):

   • "analyze csv"
   • "process data file"
   • "generate statistics"

4. Re-validate:

   python scripts/validate_standards.py --plugin-root .
   

Validator Checks:

• SKILL_015: Must contain "Use when" (case-insensitive)
• SKILL_016: Must contain trigger phrases

6.4 "CRITICAL: .claude-plugin/ contains extra files"

Symptom:

[CRITICAL] DIR_002
  Expected: ONLY plugin.json in .claude-plugin/
  Actual: Found: plugin.json, README.md, config.json
  Fix: Remove all files except plugin.json from .claude-plugin/

Cause: Components or docs placed inside .claude-plugin/ instead of plugin root.

Recovery:

1. Move components to root:

   # If you have skills in .claude-plugin/
   mv .claude-plugin/skills/ ./
   
   # If you have docs in .claude-plugin/
   mv .claude-plugin/README.md ./
   

2. Remove extra files:

   cd .claude-plugin
   ls -a
   # Should show ONLY: . .. plugin.json
   
   # Remove any extra files
   rm README.md config.json
   

3. Re-validate:

   python scripts/validate_standards.py --plugin-root .
   

Validator Check: DIR_002 enforces strict .claude-plugin/ contents

7. Validator Mapping Table (Comprehensive)

7.1 All Check IDs by Category

7.2 Critical Path Checks (Must Pass for PR Merge)

8. References

8.1 Related Standards

• 6767-c: Extensions Standard (comprehensive policy)
• 6767-d: Extensions Schema (validation rules)
• 6767-e: Validation and CI Gates (enforcement)
• 6767-g: Skill Scaffold Diagrams (companion document)

8.2 Tools

• Validator Reference: /scripts/validate_standards.py
• CI Templates: .github/workflows/
• Diagram Tools: Mermaid (https://mermaid.js.org/)

END OF SPECIFICATION

Version: 3.0.0 Status: CANONICAL (Enterprise-Only) Date: 2025-12-20