Artifacts

Product and roadmap

00-product/product.md is the most stable artifact: problem, users, outcomes, principles, non-goals, and the Definition of Done that working-story and reviewing-story use. 01-roadmap/roadmap.md is strategic (Now, Next, Later), not a list of story checkboxes; epics carry a horizon instead. Neither file has frontmatter, and not every heading needs to be filled in at once.

Epics

An epic is a larger outcome. It answers why it matters, what changes for the user, what is in and out of scope, and how we will know it worked. Name it after the outcome ("Support team collaboration"), not the work ("Change DB schema and update components").

Copy---
schema: 1
type: epic
id: EPIC-7M4K2P9Q
title: Social authentication
status: active
horizon: now
priority: p1
---
 
# Social Authentication
 
## Problem
## Outcome
## Scope
## Non-goals
## Success
## Constraints

An epic does not list its stories. Each story says epic: EPIC-..., and agileflow work show <epic> derives the list. An epic cannot be closed cleanly while it has unfinished stories.

Stories

A story is an independently actionable slice of work. It does not need an epic: small bugs and improvements are standalone stories. A bug is a story; there is no separate bug or task artifact.

Copy---
schema: 1
type: story
id: STORY-3Q7MX2PK
title: Add Google sign-in
status: ready
priority: p1
epic: EPIC-7M4K2P9Q
depends_on: []
---
 
# Add Google sign-in
 
## Why
## Outcome
## Acceptance Criteria
 
- [ ] Google appears as an authentication option.
- [ ] A new Google user can create an account.
 
## Constraints
 
- Follow DEC-4C8M2Q7K for authentication provider integration.

Fields such as assignee, points, sprint, component, labels, or timestamps are not part of schema 1; check warns about unknown fields.

Acceptance criteria are Markdown checkboxes describing observable completion. Check one (- [x]) only after verifying it, not because code was written.

Statuses

Recommended flow:

Copybacklog → ready → in-progress → in-review → done
 
in-progress → blocked      blocked → ready
ready       → blocked      blocked → in-progress
in-review   → blocked      in-review → in-progress
done        → in-progress  (reopen)
any active state → cancelled

in-progress → done is also normal where the repository has no review step. Other moves are allowed with a warning: the workflow is a default, not a prison.

Epics follow proposed → active → done (plus cancelled, and done → active to reopen). Decisions follow proposed → accepted → superseded, or proposed → rejected. The same rule applies: other moves warn but are allowed.

Decisions

Record a decision only when future work would otherwise rediscover the same choice and the reasoning matters: architecture, product constraints, providers, storage, compatibility. Not every choice.

Copy---
schema: 1
type: decision
id: DEC-4C8M2Q7K
title: Use Auth.js for social authentication
status: accepted
related:
  - EPIC-7M4K2P9Q
---
 
# Use Auth.js for social authentication
 
## Context
## Decision
## Why
## Consequences

Statuses: proposed, accepted, superseded, rejected. related is optional.

IDs and file names

IDs are TYPE-XXXXXXXX: EPIC-, STORY-, or DEC- plus 8 random Crockford Base32 characters (0-9 and A-Z without I, L, O, U). There is no counter and no next-id file, so branches, worktrees, and parallel agents never create the same ID. IDs never change.

Files are named <ID>-<initial-slug>.md. The ID in the frontmatter is authoritative; the slug is for humans and is not renamed when the title changes. Commands accept unambiguous prefixes: 3Q7M, STORY-3Q7, or 7m4k.

Schemas

Every structured artifact has schema: 1 (the document format, not the AgileFlow version). JSON Schemas for editors are in the repository at schemas/work/epic.schema.json, story.schema.json, and decision.schema.json.