Skip to content

plugin-design-template-full.md

Latest commit

 

History

History
489 lines (359 loc) · 15.6 KB

plugin-design-template-full.md

File metadata and controls

489 lines (359 loc) · 15.6 KB

[Plugin Name] — Design Document

Version: 0.1 (Draft) Status: In Progress — NOT FOR IMPLEMENTATION Last Updated: YYYY-MM-DD Authors: TBD Reviewers: TBD

Table of Contents

  1. Overview & Problem Statement
  2. Goals & Non-Goals
  3. Design Principles
  4. Plugin Architecture
  5. Core Workflows
  6. Domain-Specific Core Section
  7. Testing Strategy
  8. Open Questions & Decisions Log
  9. Appendix

1. Overview & Problem Statement

[Describe the problem statement here.]

2. Goals & Non-Goals

Goals

  • [Goal 1]
  • [Goal 2]
  • [Goal 3]

Non-Goals

  • [Non-goal 1]
  • [Non-goal 2]
  • [Non-goal 3]

3. Design Principles

Preamble

[Preamble here.]

P1 — [Principle Name]

Statement: [One declarative sentence — a decision rule the plugin follows when under implementation pressure. It should tell you what to do in a specific situation, not just express a value.]

Intent: [What specific failure mode does this principle prevent? Name it concretely. The minimum bar: "Prevents [specific bad outcome] that would otherwise occur when [specific pressure]." If no concrete failure mode comes to mind, the principle may be too vague.]

Enforcement Heuristic: [What does a violation look like in practice? Name a specific code pattern, architectural choice, or behavior. E.g., "A hook script that exits non-zero on failure" or "A command that runs a destructive operation without first surfacing a summary for user confirmation." Be specific enough that another developer could identify a violation without asking you.]

Cost of Following This Principle: [What does this plugin or user give up to honor this principle? There must be a real cost. If following this principle is free, it's not a principle — it's a platitude. E.g., "The plugin gives up the ability to run silently end-to-end without user involvement, because confirmation gates are required at key decision points."]

Tiebreaker: [If this principle conflicts with another principle in this plugin, which one wins? State the rule. E.g., "When P2 and P3 conflict, P2 takes precedence — correctness over speed." If no conflict is expected: "None."]

Risk Areas: [Which parts of this plugin are most likely to violate this principle under implementation pressure? E.g., "The session-end hook, where the temptation is to skip the queue review to reduce friction."]

4. Plugin Architecture

Components

Commands (/[name] <subcommand>)

Skills

  • [skill-name]: [When does Claude invoke this contextually?]

Hooks

  • [hook-event] → [script-name.sh]: [What does this hook detect/enforce?]

Scripts

  • [script-name.sh]: [Called by? Does what?]

Agents (if applicable)

  • [agent-name]: [What task does it handle? What tool restrictions apply?]

MCP Server (if applicable)

  • [server-name]: [What tools does it expose?]

State & Configuration Files

~/.plugin-name/
  config.yaml        # [Purpose. Format. What breaks if absent?]
  state.json         # [Purpose. Format. What breaks if corrupted?]
  cache/
    snapshot.json    # [Purpose. Invalidation policy.]

# ~/.plugin-name/config.yaml (example)
field-one: value     # [What does this field control?]
field-two: value     # [What does this field control?]

Context Cost Model

Component Enters context? When?
Command markdown Yes On /[name] invocation
Skills Conditionally When Claude deems relevant
Hook scripts No Run externally; only stdout returned
Scripts No Run externally; only stdout returned
Agent definitions No (for parent) Loaded by spawned agent
[State file summary] Yes [When?]

Failure Modes & Graceful Degradation

Failure Detection Behavior Recovery
Config file missing [How?] [What happens?] [How to recover?]
[External dependency] unavailable [How?] [What happens?] [Recovery command?]
State file corrupted [How?] [What happens?] [Recovery?]

5. Core Workflows

[Workflow 1 Name]

  1. [Step 1] [→ P1]
  2. [Step 2]
  3. [Step 3] [→ P2]

[Workflow 2 Name]

  1. [Step 1]
  2. [Step 2]

[Error/Edge Case Workflow]

  1. [Step 1]

6. Domain-Specific Core Section

7. Testing Strategy

7.1 Self-Test (/[name] status --test)

Self-test checks (all read-only, non-destructive):

  • [Check 1: e.g., config file exists and contains required fields]
  • [Check 2: e.g., state file is valid JSON or absent]
  • [Check 3: e.g., external dependency is reachable]

7.2 Unit Tests (bats)

What bats covers:

  • Happy path: [description of core script behavior]
  • Error path: [description of failure handling]
  • Edge case: [description of boundary condition]

All bats tests use $BATS_TMPDIR/[plugin]-test/ — never production files.

7.3 Structural Tests (Plugin Test Harness)

PTH checks for this plugin:

  • Hook registration: hooks.json uses the record format (keyed by event name)
  • Command structure: all commands have required frontmatter fields
  • Skill triggers: skill files have appropriate trigger metadata
  • [Plugin-specific]: [describe any non-standard structural contract]

7.4 Sandboxed Workflow Tests

Sandbox setup:

# [Commands to create a throwaway test environment]
# Override config to point at sandbox, not production state

Scenarios (one Claude session per scenario):

  1. [Scenario name] — invoke [command/trigger], verify [expected outcome]
  2. [Scenario name] — invoke [command/trigger], verify [expected outcome]
  3. Error path — [trigger failure condition], verify [expected error handling]

8. Open Questions & Decisions Log

# Question Why it matters Owner Status
OQ1 [Specific, answerable question] [Concrete consequence if unresolved] TBD Open

9. Appendix

9.1 Glossary

Term Definition
[Term] [Definition]

9.2 Command Reference

Command Description Key flags
/[name] [subcommand] [Description] --[flag]

9.3 Configuration Field Reference

Field Required Type Default Notes
[field-name] ✓ string — [What it controls, what breaks if wrong]