Spec document structure, formatting rules, and guidelines for updating .workaholic/specs/.
From standardsnpx claudepluginhub qmu/workaholic --plugin standardsThis skill is limited to using the following tools:
sh/gather.shGuidelines for writing and updating specification documents in .workaholic/specs/.
Run the bundled script to collect information about what changed:
bash ${CLAUDE_PLUGIN_ROOT}/skills/write-spec/sh/gather.sh [base-branch]
Default base branch is main.
The script outputs structured information:
=== BRANCH ===
<current branch name>
=== TICKETS ===
<list of archived tickets for this branch, or "No archived tickets">
=== SPECS ===
<list of existing spec files>
=== DIFF ===
<git diff stat against base branch>
=== COMMIT ===
<current short commit hash>
=== ACTUAL STRUCTURE ===
<actual files in plugins/drivin/ directories>
commit_hash field| Audience | Directory | Content |
|---|---|---|
| Users | .workaholic/guides/ | How to use: commands, workflows, setup |
| Developers | .workaholic/specs/ | How it works: viewpoint-based architecture specs |
The specs directory contains 8 viewpoint-based architecture documents (plus their Japanese translations):
| Viewpoint | File | Description |
|---|---|---|
| stakeholder | stakeholder.md | Who uses the system, their goals, interaction patterns |
| model | model.md | Domain concepts, relationships, core abstractions |
| usecase | usecase.md | User workflows, command sequences, input/output contracts |
| infrastructure | infrastructure.md | External dependencies, file system layout, installation |
| application | application.md | Runtime behavior, agent orchestration, data flow |
| component | component.md | Internal structure, module boundaries, decomposition |
| data | data.md | Data formats, frontmatter schemas, naming conventions |
| feature | feature.md | Feature inventory, capability matrix, configuration |
Each viewpoint file may have a corresponding translation file (e.g., stakeholder_ja.md when the primary language is English). The translation suffix depends on the consumer project's CLAUDE.md language configuration.
Required for every spec file:
---
title: Document Title
description: Brief description of this document
category: user | developer
modified_at: <ISO 8601 datetime>
commit_hash: <from context COMMIT section>
---
stakeholder.md, component.md_ja suffix: stakeholder_ja.md, component_ja.mdgetting-started.md, command-reference.mdREADME.md and README_ja.md use uppercase.workaholic/Before updating individual docs, analyze changes for patterns that span multiple components:
For each cross-cutting concern:
.workaholic/specs/ already has a document covering this conceptWriting cross-cutting documentation:
Viewpoint spec index entries:
The README files should list all 8 viewpoint specs:
# README.md
- [Stakeholder](stakeholder.md) - Who uses the system, their goals, interaction patterns
- [Model](model.md) - Domain concepts, relationships, core abstractions
- [Use Case](usecase.md) - User workflows, command sequences, input/output contracts
- [Infrastructure](infrastructure.md) - External dependencies, file system layout, installation
- [Application](application.md) - Runtime behavior, agent orchestration, data flow
- [Component](component.md) - Internal structure, module boundaries, decomposition
- [Data](data.md) - Data formats, frontmatter schemas, naming conventions
- [Feature](feature.md) - Feature inventory, capability matrix, configuration
When adding a document:
When removing a document:
i18n README mirroring:
translate skill for translation requirements.workaholic/ - Safety constraint for file deletionscategory: user must be in guides/, category: developer in specs/modified_at - Set to current datetime (use date -Iseconds) when modifying any doccommit_hash - Use value from context COMMIT section