Interface Management Skill

Enforcement

Execution mode: Select workflow and execute immediately using documented script commands.

Prohibited actions:

• Do not invoke scripts with arguments other than those documented in workflow steps
• Do not skip confirmation steps for delete operations
• Do not create interfaces without automatic numbering via the create workflow

Constraints:

• Run scripts EXACTLY as documented using python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface ...
• Always validate interface format after creation or update using ref-asciidoc
• Interface specifications must be stored in doc/interfaces/ directory

---

Manage Interface specifications stored in doc/interfaces/ directory.

Purpose

Provide structured management of interface documentation:

• Create interface specs with automatic numbering and template
• Read interface content by number
• Update interface specifications
• Delete interfaces when necessary
• List all interfaces with optional filtering
• Validate interface format using ref-asciidoc

Available Workflows

Workflow	Purpose	Script Used
list-interfaces	List all interfaces with optional filtering	manage-interface.py list
create-interface	Create new interface from template	manage-interface.py create
read-interface	Read interface content	manage-interface.py read
update-interface	Update interface content	manage-interface.py update
delete-interface	Delete interface (with confirmation)	manage-interface.py delete
validate-interface	Validate interface format	ref-asciidoc workflows

Workflow: list-interfaces

List all interfaces with optional type filtering.

Parameters

• type (optional): Filter by type (REST_API, Event, gRPC, Database, File, Other)

Steps

Step 1: Execute List

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface list [--type {type}]

Step 2: Parse Output

Parse TOON output containing interface list with metadata.

Output

status: success
operation: list
count: 2
interfaces[2]{number,title,type,path}:
1,User Service API,REST_API,doc/interfaces/001-User_Service_API.adoc
2,Event Bus,Event,doc/interfaces/002-Event_Bus.adoc

Workflow: create-interface

Create a new interface specification with automatic numbering.

Parameters

• title (required): Interface name
• type (required): Interface type (REST_API, Event, gRPC, Database, File, Other)

Steps

Step 1: Create Interface

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface create --title "{title}" --type "{type}"

Step 2: Parse Output

Extract created file path from TOON output.

Step 3: Open for Editing

Read the created file and inform user to fill in content sections.

Step 4: Validate Format

Skill: pm-documents:ref-asciidoc
Execute workflow: validate-format
Parameters:
  target: {created_path}

Output

Interface Created: doc/interfaces/003-{title}.adoc
Number: INTER-003
Type: REST_API

Next steps:
1. Edit doc/interfaces/003-{title}.adoc to fill in:
   - Contract definition (request/response)
   - Error handling
   - Authentication requirements
   - Examples
2. Add consumers and providers

Workflow: read-interface

Read interface content by number.

Parameters

• number (required): Interface number (1, 2, 3, etc.)

Steps

Step 1: Read Interface

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface read --number {number}

Step 2: Display Content

Show interface metadata and content to user.

Workflow: update-interface

Update interface field content.

Parameters

• number (required): Interface number
• field (required): Field to update (overview, type, input, output, errors, auth, versioning, consumers, providers)
• value (required): New value for the field

Steps

Step 1: Update Interface

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface update --number {number} --field {field} --value "{value}"

Step 2: Confirm Update

Report updated field to user.

Workflow: delete-interface

Delete interface with confirmation.

Parameters

• number (required): Interface number
• force (required): Must be true to confirm deletion

Steps

Step 1: Delete Interface

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface delete --number {number} --force

Step 2: Confirm Deletion

Report deletion to user.

Workflow: validate-interface

Validate interface format using ref-asciidoc skill.

Parameters

• number (required): Interface number to validate

Steps

Step 1: Find Interface Path

Use list-interfaces workflow to get interface path by number.

Step 2: Validate Format

Skill: pm-documents:ref-asciidoc
Execute workflow: validate-format
Parameters:
  target: {interface_path}

Step 3: Report Results

Report validation results to user.

Integration with ref-asciidoc

This skill integrates with ref-asciidoc for:

• Format validation: Ensures AsciiDoc formatting compliance
• Link verification: Validates cross-references
• Content review: Reviews interface content quality

Interface Types

Type	Description
REST_API	HTTP/REST service endpoints
Event	Event-driven message contracts
gRPC	gRPC service and message definitions
Database	Database schema and access contracts
File	File format and exchange specifications
Other	Other interface types

Interface Template Structure

Each interface specification contains these sections:

1. Overview - Brief description of the interface
2. Interface Type - REST_API, Event, gRPC, Database, File, Other
3. Contract Definition - Request/Input, Response/Output, Error Handling
4. Authentication & Authorization - Security requirements
5. Versioning - Version strategy and compatibility
6. Examples - Request and response examples
7. Consumers - Systems that consume this interface
8. Providers - Systems that provide this interface
9. References - Related documents and links

File Naming Convention

Interfaces follow this naming pattern:

doc/interfaces/{NNN}-{Title_With_Underscores}.adoc

Examples:

• doc/interfaces/001-User_Service_API.adoc
• doc/interfaces/002-Event_Bus_Interface.adoc
• doc/interfaces/003-Database_Schema_V2.adoc

Scripts

Script: pm-documents:manage-interface → manage-interface.py

Subcommand	Description
list	List all interfaces with optional type filtering
create	Create new interface from template with automatic numbering
read	Read interface content by number
update	Update interface field content
delete	Delete interface (requires --force)

Usage Examples:

# List all interfaces
python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface list

# Create new interface
python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface create --title "User Service API" --type REST_API

# Update interface field
python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface update --number 1 --field overview --value "Updated description"

Canonical invocations

The canonical argparse surface for manage-interface.py. The plugin-doctor missing-canonical-block rule checks that this section is PRESENT, matching its heading only — the body is never read; manage-invocation-invalid derives its accept-set from a live --help walk rather than from this section. Consuming docs xref this section by name instead of restating the command inline. See pm-plugin-development:plugin-script-architecture cross-skill-integration.md § "Script invocation in documentation".

list

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface list \
  [--type {REST_API,Event,gRPC,Database,File,Other}]

create

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface create \
  --title TITLE --type {REST_API,Event,gRPC,Database,File,Other}

read

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface read --number NUMBER

update

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface update \
  --number NUMBER [--field FIELD] [--value VALUE]

delete

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface delete --number NUMBER [--force]

next-number

python3 .plan/execute-script.py pm-documents:manage-interface:manage-interface next-number

Related Skills

• pm-documents:ref-asciidoc - Format validation