skills.rest
23min
23minCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

aiwf-promote

Advances aiwf entity and acceptance criterion statuses through validated transitions recorded as single git commits.

Updated May 9, 2026
Search Tags:#acceptance criteria#project tracking#git commit#status transition#finite state machine#aiwf#tdd phase
One-click install
npx skills add https://github.com/23min/aiwf --skill aiwf-promote-23min
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: aiwf-promote
Source: https://github.com/23min/aiwf/tree/main/internal/skills/embedded/aiwf-promote
Command: npx skills add https://github.com/23min/aiwf --skill aiwf-promote-23min

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When AI-assisted projects track planning state as markdown entities, status changes made by hand break the audit trail and can violate the legal lifecycle of each entity kind. This Skill runs aiwf promote so every status or TDD-phase move is checked against the kind's allowed transitions and recorded as one commit with structured trailers. ## Core Features & Use Cases - Validated status transitions: Promotes epics, milestones, ADRs, gaps, decisions, contracts, and acceptance criteria only through legal moves, refusing illegal transitions before any disk change. - AC TDD phase stepping: Steps an acceptance criterion through red, green, refactor, and done phases via composite ids like M-NNNN/AC-N. - Resolver and provenance flags: Records what addressed a gap or superseded an ADR atomically with the status flip, supports --force --reason for exceptional moves, --audit-only for backfilling, and actor/principal provenance for agent-authorized work. - Use Case: A milestone's tests pass and the user says "mark M-0007 done"; the Skill runs aiwf promote M-0007 done, the kernel validates the transition, and the change lands as a single commit with aiwf-verb: promote trailers. ## Quick Start Ask the assistant to promote an entity to a new status, for example: promote milestone M-0007 to done using aiwf.

Frequently Asked Questions about aiwf-promote

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

FAQPage Schema
How do I change an aiwf entity status?▼

Run `aiwf promote <id> <new-status>` for a top-level entity, or `aiwf promote <M-NNNN>/AC-N <new-status>` for an acceptance criterion. The kernel validates the move against the kind's legal transitions and commits the change with structured trailers.

How do I step an acceptance criterion through TDD phases?▼

Use `aiwf promote <M-NNNN>/AC-N --phase <p>` where the phase is red, green, refactor, or done. Phases are linear with refactor optional, and `--phase` cannot be combined with a positional status or used on bare entity ids.

What statuses are allowed for each aiwf entity kind?▼

Epics use proposed, active, done, cancelled; milestones use draft, in_progress, done, cancelled; ADRs and decisions use proposed, accepted, superseded, rejected; gaps use open, addressed, wontfix; contracts add deprecated and retired. ACs use open, met, deferred, cancelled.

Why does aiwf promote refuse my status transition?▼

The per-kind legal-transition function rejects illegal moves, such as jumping an epic from proposed directly to done, before any disk change. For rare exceptional moves, pass `--force --reason "<text>"`, which relaxes only the FSM rule while coherence checks still run.

Can I record a status change that already happened manually?▼

Yes, use `aiwf promote <id> <state> --audit-only --reason "..."` to write an empty-diff commit with the trailer block so `aiwf history` reflects the move. The entity must already be at the named state, and audit-only is mutually exclusive with `--force`.

When should I not hand-edit the status field in markdown?▼

Never hand-edit `status:` in the markdown files, because the trailer chain disappears and `aiwf history` will not surface the move. Always use the verb route so the status change and any resolver fields land atomically in one commit.

Related Skills

Explore More Software Engineering Skills→
CarlosQ96CarlosQ96

create-stories

Break epics into implementable story files with acceptance criteria and ADR guidance.

Community
Advanced
open-haxopen-hax
6

git-safety-check

Check git branch, working tree, remotes, and submodules before destructive operations.

Official
Intermediate
MartinStykMartinStyk
343

git-commit-author

Enforce human-only authorship in git commits by blocking AI-generated trailers.

Community
Basic
sixerssixers

fakturownia-invoice-cancel

Cancel a specific invoice in Fakturownia via the CLI with an optional reason.

Community
Intermediate