fx-alfred 0.8.0

CLI for the Alfred document management system

alfred

A minimal, self-consistent document management system built on PDCA + Johnny Decimal.

Quick Start

pip install fx-alfred
cd my-project
af guide

Layer System

Alfred uses a 3-layer document model:

Layer	Location	Description
PKG	Bundled with fx-alfred	COR reference documents — read-only, always available
USR	~/.alfred/	Your personal documents, shared across all projects
PRJ	./rules/	Project-specific documents

For LLMs: How This System Works

1. Read these files first

af read COR-0001    # glossary — all terms and abbreviations
af list             # index of all available documents across all layers

2. File naming format

<PREFIX>-<ACID>-<TYP>-<Title>.md

• PREFIX: COR (universal) or 3-letter project code (ALF, BLA, CLR)
• ACID: 4-digit Johnny Decimal number (Area + Category + Item)
• TYP: 3-letter type code (SOP, ADR, CHG, INC, PLN, PRP, REF)

3. PDCA areas (meta layer)

Area	Phase	What it covers
10xx	Do	Create and read documents
11xx	Plan	Decision records and change requests
12xx	Check	Session retrospective
13xx	Act	Update, deprecate, maintain index
14xx	Constraint	Universal rules (atomicity, language policy)
15xx	Development	TDD, GitHub issues, git branch naming

4. Key rules

• COR-1400: Every SOP does exactly one thing (atomic)
• COR-1401: All documents in English
• COR-1402: Always declare which SOP is being followed before starting a task

5. To create a new document

Follow COR-1001 (Create Document) for naming and numbering, then the type-specific SOP.

Supported types: sop, adr, chg, inc, pln, prp, ref

# Specify an exact ACID
af create sop --prefix ALF --acid 2100 --title "My SOP"

# Auto-assign the next available ACID in an area
af create adr --prefix ALF --area 21 --title "Use PostgreSQL"

# Write to user layer (~/.alfred/)
af create sop --prefix USR --acid 3000 --title "My Rule" --layer user

# Write to a subdirectory of the user layer
af create sop --prefix USR --acid 3000 --title "My Rule" --layer user --subdir my-project

The index is updated automatically after each create (project layer only). To update it manually, run af index.

6. To update an existing document

Use af update to modify metadata fields, append Change History, or rename documents.

# Update a field
af update FXA-2107 --status "Completed"

# Append a Change History entry
af update FXA-2107 --history "Implementation done" --by "Claude"

# Rename a document (changes filename + H1 + index)
af update COR-1600 --title "Workflow Direct Review Loop" -y

# Preview changes without writing
af update FXA-2107 --status "Done" --dry-run

# Combine multiple updates
af update FXA-2107 --status "Completed" --history "All steps done" --field "Priority" "High"

Only PRJ and USR layer documents are writable. PKG layer documents are read-only.

Installing into another project

pip install fx-alfred
af guide

Then create project documents with af create and view them with af list.

Version control

This project uses git.

git log             # view history
git status          # current changes
git push            # push to GitHub