AZQ is a filesystem-backed craft pipeline for turning early thought into durable work.

It is built around a simple rule:

spark -> goal -> deliverable -> task -> artifact -> archive

In the current live repository, AZQ can already carry work through the first visible baseline:

spark -> goal -> deliverable -> task -> dag

The code lives under azq/. The visible system of record lives under data/.

If you can inspect the files on disk, you can inspect what AZQ believes is true.

AZQ is organized around five public craft layers:

These names are not decoration. They are the intended order of work.

AZQ is trying to keep you from jumping straight from a vague idea to an undifferentiated task list.

The current baseline is real code, not just planning docs:

• azq/scintilla/ captures audio, writes transcripts, and extracts spark records
• azq/finis/ stores canonical goal files under data/finis/goals/
• azq/formam/ builds canonical deliverables and goal maps under data/form/
• azq/agenda/ builds canonical tasks, goal-level DAG artifacts, and task logs under data/agenda/

What is not live yet:

• Domum
• azq status
• azq doctor
• archive-first replacement for every destructive path
• the deeper LLM-assisted shaping behavior planned for Finis, Formam, and Agenda

azq spark rm <id> is still live today, but it remains a temporary destructive path rather than the desired final stewardship model.

The live package root is:

azq/

The current visible craft records live under:

data/
  scintilla/
    audio/
    transcripts/
    sparks/
  finis/
    goals/
  form/
    deliverables/
    maps/
  agenda/
    tasks/
    dags/
    logs/

• data/scintilla/ is the spark layer: audio, transcript, and extracted spark JSON
• data/finis/goals/ is the canonical goal store
• data/form/deliverables/ and data/form/maps/ are the canonical Formam records
• data/agenda/tasks/, data/agenda/dags/, and data/agenda/logs/ are the canonical Agenda records

Typical filenames look like this:

data/scintilla/sparks/2026-03-09_090255.json
data/finis/goals/FINIS_001.md
data/form/deliverables/DELIV_001.md
data/form/maps/GOAL_FINIS_001_MAP.md
data/agenda/tasks/TASK_001.md
data/agenda/dags/GOAL_FINIS_001_DAG.json
data/agenda/logs/TASK_001_LOG.md

High-signal support material now lives under:

docs/architecture/
planning/
codex/
attic/

These are the live commands exposed by the repository today.

azq capture
azq sparks
azq spark <spark_id>
azq spark search "<text>"
azq spark rm <spark_id>

• azq capture starts the interactive audio capture loop, then writes audio, transcript, and spark artifacts
• azq sparks lists saved spark bundles
• azq spark <spark_id> shows one exact spark bundle
• azq spark search "<text>" searches extracted spark text
• azq spark rm <spark_id> deletes that spark bundle

azq fine
azq goals
azq goal add
azq goal close <goal_id>
azq goal archive <goal_id>

• azq fine reads sparks and proposes candidate goals through the current interactive flow
• azq goals lists active goals
• azq goal add creates a goal manually
• azq goal close <goal_id> marks a goal completed
• azq goal archive <goal_id> marks a goal archived

azq form build <goal_id>
azq form list
azq form show <deliverable_id>
azq form map <goal_id>

• azq form build <goal_id> creates the current first-form baseline for a goal
• azq form list lists deliverables
• azq form show <deliverable_id> shows one deliverable
• azq form map <goal_id> refreshes and prints the goal map path

azq agenda build <deliverable_id>
azq agenda list
azq agenda show <task_id>
azq agenda dag <deliverable_id>

• azq agenda build <deliverable_id> creates the current canonical task baseline for one deliverable
• azq agenda list lists canonical tasks
• azq agenda show <task_id> shows one canonical task
• azq agenda dag <deliverable_id> refreshes the parent goal DAG reached from that deliverable

Create and activate a virtual environment, then install AZQ in editable mode:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Check the live CLI:

azq

You should see the current command list beginning with capture, sparks, and spark <id>, and ending with the agenda ... commands.

If you want the smallest reliable proof-of-life path, see docs/architecture/AZQ_BOOTSTRAP.md.

This is the shortest good path to prove the current live baseline without requiring microphone capture.

azq goal add
azq goals

Example title:

Bootstrap the current AZQ repository

You should now have a goal file such as:

data/finis/goals/FINIS_001.md

azq form build FINIS_001
azq form list
azq form show DELIV_001
azq form map FINIS_001

You should now have:

data/form/deliverables/DELIV_001.md
data/form/maps/GOAL_FINIS_001_MAP.md

azq agenda build DELIV_001
azq agenda list
azq agenda show TASK_001
azq agenda dag DELIV_001

You should now have:

data/agenda/tasks/TASK_001.md
data/agenda/dags/GOAL_FINIS_001_DAG.json

At that point, the current live AZQ baseline is working.

If your microphone and Whisper stack are working, you can prove Scintilla too.

azq capture

Inside the capture loop:

1. start recording
2. say one short idea aloud
3. stop recording
4. wait for transcription and extraction
5. exit cleanly

Then inspect the spark layer:

azq sparks
azq spark <spark_id>
azq spark search "<text>"

If successful, you should see a spark bundle written under:

data/scintilla/audio/
data/scintilla/transcripts/
data/scintilla/sparks/

Graphite is not a live AZQ engine.

Here, Graphite is used as a serious example project:

• a local-first research and thinking tool
• a workflow that combines local hardware, LLMs, and research pipelines
• a way to produce documented, source-aware, actionable understanding on focused topics

The point of this example is to use the current AZQ baseline to shape Graphite into visible work.

You can either promote a spark through azq fine or create the goal directly:

azq goal add

Example goal title:

Stabilize Graphite MVP around document triage and source-aware ranking

Example description:

Use the current Graphite repository to define and build the smallest working research pipeline that, given a directory of documents, identifies which ones matter most and explains why.

List goals:

azq goals

azq form build FINIS_001
azq form list
azq form show DELIV_001
azq form map FINIS_001

This creates the first visible structural artifact for the goal.

azq agenda build DELIV_001
azq agenda list
azq agenda show TASK_001
azq agenda dag DELIV_001

This creates the current executable-work baseline.

Check:

data/finis/goals/FINIS_001.md
data/form/deliverables/DELIV_001.md
data/form/maps/GOAL_FINIS_001_MAP.md
data/agenda/tasks/TASK_001.md
data/agenda/dags/GOAL_FINIS_001_DAG.json

At that point, Graphite has moved through the live AZQ path:

spark -> goal -> deliverable -> task -> dag

That is enough to prove that AZQ can hold the shape of real work before the deeper shaping layers are added.

The near-term direction is:

1. deepen Finis into an LLM-assisted goal-shaping layer
2. deepen Formam into an LLM-assisted deliverable-shaping layer
3. deepen Agenda into an LLM-assisted task-and-Codex layer
4. implement Domum
5. add repository-wide status and doctor
6. remove destructive delete paths

That order matters.

AZQ is not trying to bolt intelligence on from the outside. It is trying to deepen the existing craft layers so the engines mean what their names imply.

If you want the shortest route into the repository:

• start here in README.md
• use docs/architecture/AZQ_BOOTSTRAP.md to prove the live baseline
• use docs/architecture/AZQ_COMMAND_MODEL.md to understand the CLI shape
• use docs/architecture/AZQ_ENGINE_SPEC.md to understand what each engine owns
• use docs/architecture/AZQ_FILESYSTEM_MODEL.md to understand where artifacts live
• use docs/architecture/AZQ_IMPLEMENTATION_PLAN.md to understand what comes next
• use docs/architecture/AZQ_PHILOSOPHY.md only when you want the deeper why

AZQ is not trying to be a generic todo app.

It is trying to become a craft system that:

• gathers sparks without losing them
• shapes goals before they become slogans
• shapes deliverables before they explode into tasks
• shapes executable work before it dissolves into chaos
• eventually preserves and reviews what was built

Right now, the live baseline is smaller than that full ambition.

That is okay.

The important thing is that the current baseline is real, inspectable, and running.