skills.rest
yogata
yogataCOMMUNITY
Explore all skills by this author →
GitHub

agentdev-decision-file-manager

Manages decision record file creation, appending, updating, and numbering under docs/decisions.

Updated Mar 7, 2026
Search Tags:#documentation#markdown#adr#decision records#numbering#status lifecycle#consistency validation
One-click install
npx skills add https://github.com/yogata/agent-dev-flow --skill agentdev-decision-file-manager-yogata
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agentdev-decision-file-manager
Source: https://github.com/yogata/agent-dev-flow/tree/main/src/opencode/skills/agentdev-decision-file-manager
Command: npx skills add https://github.com/yogata/agent-dev-flow --skill agentdev-decision-file-manager-yogata

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Keeping architecture decision records consistent is hard: numbers get reused, statuses transition illegally, and the README index drifts out of sync with actual Decision files. This Skill enforces deterministic numbering, valid status transitions, and index consistency for all Decision files. ## Core Features & Use Cases - Deterministic Number Allocation: Allocates DEC-NNN identifiers as max+1 via a self-contained script, never filling gaps from retired numbers. - Three Operation Modes: CREATE new Decision files from a template, APPEND supplementary sections, or UPDATE existing content and statuses with strict transition rules (proposed → accepted → deprecated/superseded). - Consistency Validation: Checks frontmatter fields, superseded_by links, related_reqs references, and README classification views against actual files. - Use Case: When finalizing a requirement definition, create a new Decision record with an automatically allocated number, proposed status, and a synchronized entry in the docs/decisions README index. ## Quick Start Create a new decision record for the chosen caching strategy and add it to the decisions index.

Frequently Asked Questions about agentdev-decision-file-manager

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

FAQPage Schema
How do I create a new architecture decision record file?▼

Run the allocation script with the decisions directory to get the next DEC-NNN number, then apply the decision template with status proposed. The README index must be updated in the same change as the new file.

How is the next decision record number allocated?▼

The alloc-decision-number script scans existing DEC-NNN files in docs/decisions, finds the maximum number, and returns max+1 as JSON. Gap numbers from retired decisions are never reused.

What status transitions are allowed for decision records?▼

Allowed transitions are proposed to accepted, proposed to deprecated, accepted to deprecated, and accepted to superseded with a superseded_by field. Reverse transitions like accepted to proposed and any transition from deprecated or superseded are forbidden.

Can I edit an accepted decision record directly?▼

Only non-semantic fixes are allowed on accepted decisions, such as typo corrections, broken link fixes, and metadata updates. Any semantic change to the decision content requires creating a new superseding decision instead.

When should I not create a new decision record?▼

Do not create a new decision when merely removing, deprecating, or migrating a past decision; use a status transition to deprecated or superseded instead. New decisions are only for decisions about a desired future state.

Related Skills

Explore More Software Engineering Skills→
lyndonkllyndonkl
142

adr-architecture

Document architectural decisions using the Architecture Decision Record format.

Community
Advanced
lilmuckerslilmuckers

wiki-first-product-management

Organize project definition and architecture in the GitHub wiki.

Community
Intermediate
jimuttjimutt
4

dld-audit-auto

Audit code annotations against decision records and open a pull request with fixes.

Community
Advanced
rnavarychrnavarych
14

role-architect:adr-writer

Write structured Architecture Decision Records with numbering and lifecycle status management.

Community
Intermediate