From Vengineer
Transform design docs, ADRs, or rough plans into proper feature specifications
npx claudepluginhub dylanliiii/shipyard --plugin VengineerThis skill is limited to using the following tools:
**Purpose**: Transform existing design documents, Architecture Decision Records (ADRs), or rough plans into well-structured feature specifications following the project's spec template.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Automates semantic versioning and release workflow for Claude Code plugins: bumps versions in package.json, marketplace.json, plugin.json; verifies builds; creates git tags, GitHub releases, changelogs.
Purpose: Transform existing design documents, Architecture Decision Records (ADRs), or rough plans into well-structured feature specifications following the project's spec template.
$ARGUMENTS
If the input above is empty, use AskUserQuestion to ask: "Please provide a file path to your design doc/ADR/rough plan, or paste the content directly."
Do not proceed until you have material to transform.
Determine input type and load accordingly:
docs/sketches/2026-01-15-auth.md, docs/plans/rough-plan.md): Read the file using the Read tool.Also load the spec template for reference:
plugins/Vengineer/skills/reference/spec_template.md
Parse the source material and extract:
| Element | What to Look For |
|---|---|
| Feature Name | Title, heading, or dominant topic |
| Actors | Who uses this — users, admins, systems, services |
| Core Actions | What users/systems do — verbs and flows described |
| Constraints | Limitations, scope boundaries |
| Non-Goals | Explicit exclusions: "out of scope", "not included", "future work", "does not cover", deferred items |
| Success Signals | Goals, KPIs, "done when" statements |
| Decisions Made | ADR rationale, chosen approaches, rejected alternatives |
| Open Questions | Unresolved items, TBDs, items marked for future |
| Data Entities | Models, schemas, key objects mentioned |
Note: Design docs and ADRs often contain implementation details (tech stack, APIs, framework choices). Strip these during extraction — the spec must remain implementation-agnostic.
Using the loaded spec template, map extracted content to spec sections:
###-feature-name (use 000 if no issue number is known)For each distinct user flow found in the source:
FR-XXX: System MUST [capability] statements[NEEDS CLARIFICATION: specific question][NEEDS CLARIFICATION] markers totalNG-XXX: [What this feature will NOT do or support]SC-XXX: [Measurable metric from user/business perspective]Write the completed spec to docs/specs/<feature-name>.md using the template structure.
Add YAML frontmatter at the top of the spec file:
---
stage: spec
created: YYYY-MM-DD
feature: <feature-name>
source-sketch: <path to input sketch file if input was from docs/sketches/, else omit>
status: draft
---
If the input was from docs/sketches/, also update the sketch file's frontmatter to add:
next-spec: docs/specs/<feature-name>.md
Use the Edit tool to append this field inside the existing --- block without corrupting other fields.
Quality rules (apply before writing):
If [NEEDS CLARIFICATION] markers remain after writing:
Question: [Topic from NEEDS CLARIFICATION marker]
Context: [Relevant quote from source material]
Options:
- Option A: [Description + implications]
- Option B: [Description + implications]
- Custom: provide your own answer
After all clarifications are resolved, do a final pass:
[NEEDS CLARIFICATION] markers are resolved or removedReport the result: spec path, number of user stories, number of requirements, any remaining notes.
Use AskUserQuestion to present options:
Question: "Spec ready at docs/specs/<feature-name>.md. What would you like to do next?"
Options:
medium-plan docs/specs/<feature-name>.md — Generate implementation plan from this spec (Recommended)/core:clarify — Ask targeted questions to deepen the spec further/core:plan_review — Get feedback from specialized reviewers