aiwfx-start-epic

Activates an aiwf epic through preflight checks, sovereign promotion, and branch creation.

Updated May 9, 2026
One-click install
npx skills add https://github.com/23min/aiwf --skill aiwfx-start-epic-23min
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: aiwfx-start-epic
Source: https://github.com/23min/aiwf/tree/main/internal/skills/embedded-rituals/plugins/aiwf-extensions/skills/aiwfx-start-epic
Command: npx skills add https://github.com/23min/aiwf --skill aiwfx-start-epic-23min

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Activating an epic in an aiwf-tracked project involves several ordered steps — validating the epic spec, confirming a drafted milestone exists, running kernel checks, getting human approval for the sovereign promote commit, optionally opening a delegation scope, and cutting the epic branch. Doing this by hand risks skipping checks, bundling commits, or violating the kernel's human-only promotion rule. ## Core Features & Use Cases - Preflight validation: Reads the epic spec for concrete Goal/Scope/Constraints sections, checks for a drafted milestone via epic-active-no-drafted-milestones, and requires a clean aiwf check before proceeding. - Sovereign promotion gate: Presents aiwf promote E-NNNN active as an explicit approve/deny gate, landing the commit on main with the operator's own identity, with a --force --reason override reserved for genuine exceptions. - Optional delegation and worktree setup: Supports opening an aiwf authorize scope to an ai/<id> agent bound to the future epic branch, then cuts epic/E-NNNN-<slug> with in-repo worktree placement as the default. - Use Case: When a user says "start E-0007" or "let's begin work on the auth epic", the skill walks the operator through readiness checks, the gated promote commit, and branch creation, then hands off to aiwfx-start-milestone. ## Quick Start Ask the assistant to start epic E-NNNN, for example by saying "start E-0007" or "activate the auth epic", and approve the promotion command when prompted.

Frequently Asked Questions about aiwfx-start-epic

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

FAQPage Schema
How do I start or activate an epic in aiwf?

Say "start E-NNNN" or "activate the <name> epic" to trigger the activation workflow. It runs preflight checks, presents `aiwf promote E-NNNN active` as an approve/deny gate, and cuts the `epic/E-NNNN-<slug>` branch after your approval.

Why does aiwf promote epic to active fail for an AI actor?

The kernel's sovereignty rule refuses `aiwf promote E-NNNN active` from any actor not prefixed `human/`. The skill runs the bare command so it resolves to the operator's own git identity; the `--force --reason` override exists only for genuine exceptions and still requires a human actor.

What preconditions must an epic meet before activation?

The epic spec must exist with status `proposed` and concrete Goal, Scope, Out of scope, and Constraints sections. At least one milestone under it must have status `draft`, and `aiwf check` must report no error-severity findings touching the epic.

Can I delegate an aiwf epic to an AI agent?

Yes. During activation you can choose delegation, which runs `aiwf authorize E-NNNN --to ai/<id> --branch epic/E-NNNN-<slug>` as a separate commit on `main` before the branch is cut. The named agent then operates within that scope until the epic closes or the scope is paused.

Where does the epic worktree get created in aiwf?

The default is in-repo under the configured `worktree.dir` (typically `.claude/worktrees/<branch>/`), created with `aiwf worktree add`. You can override per invocation to work directly on the main checkout or use a sibling-directory worktree.