Implement Spec
Developmentimplement-specImplement Spec is an Agent Skill for development published in the LibPDF-js/core repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Implement a spec from the plans directory
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/LibPDF-js/core/blob/HEAD/.opencode/skills/implement-spec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/implement-spec, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
You are implementing a specification from the .agents/plans/ directory. Work autonomously until the feature is complete and tests pass.
Your Task
- Determine the spec - Based on the conversation context, identify which spec file in
.agents/plans/to implement. Ask the user if multiple specs exist or if unclear. - Read the spec - Load the identified specification file
- Read ARCHITECTURE.md - Understand the project's layered architecture and how your feature fits into the high-level/low-level API structure
- Read CODE_STYLE.md for formatting conventions
- Plan the implementation using the TodoWrite tool to break down the work
- Implement the feature following the spec and code style
- Write tests for all new functionality
- Run tests and fix any failures
- Run typecheck and lint and fix any issues
Implementation Guidelines
Before Coding
- Understand the spec's goals and scope
- Identify the desired API from usage examples in the spec
- Review related existing code to understand patterns
- Consult ARCHITECTURE.md - Determine which layer(s) your feature belongs to and how it fits into the overall structure
- Break the work into discrete tasks using TodoWrite
Architecture Patterns
Most features should implement both low-level and high-level variants:
Low-level first:
- Direct manipulation of PDF COS objects (
PdfDict,PdfArray,PdfStream) - Core functionality without ergonomic abstractions
- Typically in
src/core/or appropriate layer directory
High-level adapter:
- User-friendly methods on main classes (
PDF,PDFPage, etc.) - Validates inputs, provides defaults, handles edge cases
- Delegates to low-level implementation
Example structure:
src/
├── core/
│ └── shading.ts # Low-level: PdfStream creation
└── api/
└── page.ts # High-level: page.drawGradient()
During Implementation
- Follow CODE_STYLE.md strictly (2-space indent, double quotes, braces always, etc.)
- Use
#src/*import alias for internal imports - Co-locate tests as
*.test.tsfiles - Write tests as you go, not at the end
- Mark todos complete as you finish each task
- Commit logical chunks of work
Code Quality
- No stubbed implementations or skipped tests
- Handle edge cases and error conditions
- Include descriptive error messages with context
- Use async/await for all I/O operations
Testing
- Write tests first when practical (TDD)
- Test happy paths and edge cases
- Test error conditions
- Use fixtures from
fixtures/directory withloadFixture()
Autonomous Workflow
Work continuously through these steps:
- Implement - Write the code for the current task
- Test - Run
bun run testto verify - Fix - If tests fail, fix and re-run
- Typecheck - Run
bun run typecheck - Lint - Run
bun run lint:fix - Repeat - Move to next task
Stopping Conditions
Stop and report success when:
- All spec requirements are implemented
- All tests pass
- Typecheck passes
- Lint passes
Stop and ask for help when:
- The spec is ambiguous and you need clarification
- You encounter a blocking issue you cannot resolve
- You need to make a decision that significantly deviates from the spec
- External dependencies or fixtures are missing
Commands
bun run test # Run tests in watch mode
bun run test:run # Run tests once
bun run test -- --grep "pattern" # Run specific tests
bun run typecheck # Type check
bun run lint:fix # Fix lint issues
Begin
Identify the spec file from the conversation context, read it along with CODE_STYLE.md, then start implementing. Use TodoWrite to track your progress throughout.