majiayu000 Create Output Format
Scaffold a new output format adapter for the technical-planning workflow. Each format adapter is a directory of 5 files, one per concern.
Step 1: Gather Information
Before writing anything, understand the tool. Ask the user for:
- What is the tool/system called?
- Documentation links — official docs, API references, MCP server docs, anything relevant
If the user provided these upfront, skip straight to research.
Research
Fetch and read all provided documentation using WebFetch. From the docs, establish:
- How tasks are stored (API, database, files, etc.)
- How to interact with it (MCP server, REST API, CLI tool, filesystem)
- How to create, read, update, and query tasks
- What task properties are supported — status values, priority levels, labels/tags, estimation
- Whether it supports blocking/dependency relationships (within a project and across projects)
- How concepts map — what represents a project, a phase, a task, a dependency?
- What setup or configuration is required
- Benefits and trade-offs vs simpler approaches
- Any constraints or limitations
Clarify Gaps
Present what you've learned as a summary and ask the user to confirm or correct. Use AskUserQuestion to clarify anything the documentation didn't cover or left ambiguous — motivation for choosing this format, preferred interface if multiple exist, setup specifics, etc.
Suggest a kebab-case format key based on the tool name and confirm with the user.
Do not proceed until the user confirms your understanding.
Step 2: Understand the Contract
Read references/contract.md — this defines the 5-file interface every format must implement.
Step 3: Create the Format Directory
Create the directory at:
skills/technical-planning/references/output-formats/{format-key}/
Step 4: Write the Files
Using the information gathered in Step 1, write each of the 5 required files. Use the scaffolding templates from references/scaffolding/ as structural guides:
| Template | Creates |
|---|---|
| about.md | {format}/about.md |
| authoring.md | {format}/authoring.md |
| reading.md | {format}/reading.md |
| updating.md | {format}/updating.md |
| graph.md | {format}/graph.md |
For each file:
- Start from the scaffolding template structure
- Replace all
{placeholder}tokens with format-specific content from your gathered information - Remove template guidance comments (lines starting with
<!-- -->) - Include concrete commands, API calls, or MCP operations — not vague descriptions
Step 5: Register the Format
Add an entry to skills/technical-planning/references/output-formats.md following the existing pattern:
### {Format Name}
format: `{format-key}`
adapter: [{format-key}/](output-formats/{format-key}/)
{One-line description of the format.}
- **Pros**: ...
- **Cons**: ...
- **Best for**: ...
Step 6: Validate
Verify:
- Directory contains exactly 5 files: about.md, authoring.md, reading.md, updating.md, graph.md
- All
{placeholder}tokens have been replaced - About.md includes a structure mapping table
- Authoring.md documents task properties: status, phase grouping, labels (NOT priority or dependencies)
- Authoring.md includes a complete task creation example
- Reading.md explains next-task ordering using status, priority, dependencies, and phase
- Updating.md covers all status transitions and how to modify task properties
- Graph.md covers priority levels and adding/removing dependencies
- Format is registered in output-formats.md