opsx-annotate

Apply @spec PHPDoc tags to legacy methods from coverage reports.

1|1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/ConductionNL/shillinq --skill opsx-annotate
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: opsx-annotate
Source: https://github.com/ConductionNL/shillinq/tree/main/.claude/skills/opsx-annotate
Command: npx skills add https://github.com/ConductionNL/shillinq --skill opsx-annotate

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill addresses the lack of traceability in legacy codebases by retroactively applying spec tags to methods, ensuring that existing code is correctly mapped to requirements without requiring logic changes or refactors.

Core Features & Use Cases

  • Ghost Change Creation: Automatically generates a synthetic change artifact to serve as a stable reference point for spec tags.
  • Automated Annotation: Safely applies @spec tags to file and method docblocks across large codebases while respecting existing formatting.
  • Use Case: When a project adopts a new specification-driven development process, use this Skill to map thousands of legacy methods to their corresponding requirements in a single, clean, annotation-only PR.

Quick Start

Use the opsx-annotate skill to apply spec tags to the procest application based on the latest coverage report.

Frequently Asked Questions about opsx-annotate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add spec tags to legacy PHP code for requirement traceability?

To add spec tags to legacy PHP code, apply @spec PHPDoc tags to methods based on coverage report data. This establishes requirement traceability by performing targeted docblock edits without altering existing business logic.

What is the best way to map legacy methods to specifications without refactoring?

Mapping legacy methods to specifications without refactoring is done by creating ghost changes and applying annotation-only docblock edits. This safely retrofits traceability tags across large codebases while respecting existing formatting.

Can I apply PHPDoc annotations across both PHP and JavaScript files?

Yes, you can apply PHPDoc annotations across both PHP and JavaScript files. The annotation process performs targeted docblock edits across both file types to ensure comprehensive spec-to-code mapping.

How do coverage reports help with retroactively annotating legacy code?

Coverage reports help with retroactively annotating legacy code by providing the data used to identify methods. The Skill uses this coverage data to accurately target and apply @spec tags to the correct docblocks.

Does retrofitting spec tags alter the business logic of the existing codebase?

Retrofitting spec tags does not alter the business logic of the existing codebase. The process strictly performs annotation-only docblock edits to satisfy ADR-003 architectural requirements for spec-to-code mapping.

When do I need to create a ghost change for spec annotation?

You need to create a ghost change for spec annotation when adopting a new specification-driven development process. It serves as a stable synthetic reference point for mapping thousands of legacy methods in a single PR.