Akan.js
Docs
DocsConventionsReferencesCheatsheet
Akan.js
DocsConventionsReferencesCheatsheet
Akan.js

Released under the MIT License

Official Akan.js Consulting onAkansoftCopyright © 2026 Akan.js All rights reserved.System managed bybassman
YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
CLI Reference▾
CommandsWorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityContextAgentGuideline
AkanJS Reference▾
akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
UI Reference▾
OverviewCoreDisplayFormsOverlaysSystemAgentCustomization
YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
CLI Reference▾
CommandsWorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityContextAgentGuideline
AkanJS Reference▾
akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
UI Reference▾
OverviewCoreDisplayFormsOverlaysSystemAgentCustomization
PreviousPrimitiveNextQuality

Workflow CLI

Adding one field to a module touches five files, and most of that work is mechanical. By hand, the decisions that matter — the name, the type, the default — get lost among dictionary labels and generated barrel files, and no two modules end up quite alike.
A workflow gives that change a name: you plan it, read the plan, apply it, and validate the result. When validation fails, akan repair runs the one command that clears that failure.
Words Used on This Page
TermDescription
workflow
A named recipe for a change that always touches the same files in the same order.
plan file
The JSON plan --out writes: the steps, the files it expects to change, and the checks to run.
run artifact
What an apply, a validate or a repair leaves in .akan/workflows/runs/<runId>.json.
runId
The run artifact's file name, such as apply-20260921103000-a1b2c3.
akan repair
A narrow fix for one known kind of failure, picked by <kind>.
Reach for a workflow before a direct edit. When a workflow or a repair can make the change, use it instead of editing source by hand.

Plan, Apply, Validate

The steps form one chain, and each hands the next a file path rather than a name. That makes the plan a document you review before anything is written, and the run artifact a record of what happened.
Workflow chain
plan JSONrunIdon failure
Planworkflow plan --out
Applyworkflow apply
Validateworkflow validate
Repairakan repair
Planworkflow plan --out
plan JSON
Applyworkflow apply
runId
Validateworkflow validate
on failure
Repairakan repair
1. Plan
akan workflow plan <workflow> … --out <path>
Checks your inputs and writes the plan JSON: the steps, the files it expects to change, and the checks to run. Source is neither read nor written.
2. Apply
akan workflow apply <planPath>
Takes the plan file, not a workflow name, and writes the source changes. A plan with an error, such as a missing input, applies nothing.
3. Validate
akan workflow validate <runId | path>
Runs the checks the plan asked for — sync, lint, typecheck or build — and sorts each failure by cause.
4. Repair
akan repair <kind>
The remedy for that cause. generated re-syncs, format and imports re-lint, and the two report-only kinds name the command that fixes the module.
How Validate Sorts a Failure
CauseDescription
source-change
sync, lint or typecheck failed on the source; fix it or run a repair.
workspace-config
A workspace configuration, such as the Biome config, failed to load.
environment
The command could not run at all, such as command not found (exit code 127).
unknown
Anything else, including a failed build; read the command output in the report.
  • Known failures are marked. A config or environment failure seen on an earlier run is flagged as a known baseline blocker, unrelated to your change.
  • Doctor findings ride along. The report adds akan doctor --strict findings, split into what your change touched and what was already there. The CLI shows the second group only as counts per code.
Over MCP
akan mcp serves the same steps as tools. Plan mode reads and plans; apply mode can also write.
CommandMCP tool · mode
akan workflow list
list_workflows · plan and apply mode
akan workflow explain
explain_workflow · plan and apply mode
akan workflow plan
plan_workflow · plan and apply mode
akan workflow apply
apply_workflow · apply mode
akan workflow validate
run_validation · apply mode
akan repair generated
repair_generated · apply mode
akan repair imports
  • plan_workflow always stores its plan. Without out it writes to .akan/workflows/plans/ under a name built from the workflow and its inputs, such as add-field-koyo-icecreamorder-topping.json. It returns that planPath for apply_workflow.

Workflow Catalogue

Seven workflows ship with the CLI. akan workflow list prints each with when to use it, and akan workflow explain <name> adds its inputs, steps and validation commands.
With --format json, explain also carries the predicted changes and the completion criteria.
WorkflowDescription
create-module
A new database-backed domain module, from the constant through the store and UI. Needs: --app --module
create-scalar
A reusable value module with no database ownership, such as a value object or shared scalar. Needs: --app --scalar
create-ui
One conventional UI file for an existing module. Needs: --app --module --surface
add-field
A field on the constant and the dictionary, with the Template form flagged for review. Needs: --app --module --field --type
add-enum-field
A closed-value field: the enum class, its labels and options, and the field itself. Needs: --app --module --field --values
add-mutation
A service method and a mutation guarded by None; it only recommends a store action or UI control. Needs: --app --module --mutation
add-slice
A service query and an init slice guarded by None; it only recommends the page load and Zone. Needs: --app --module --slice
  • create-ui plans five surfaces and applies three. --surface accepts view, unit, template, zone and util; apply builds only the first three.
  • Numbers are Int or Float. A plan with --type Number carries an error, and a plan with an error applies nothing.
  • Defaults follow the type. --default is converted to match --type, and an enum default must be one of --values.
  • Two add-field inputs are MCP-only. Through plan_workflow, surfaces: ["template"] writes the field into a simple Template form and includeInLight: true adds it to the Light model.
What Validate Runs
Each workflow fixes the commands validate runs against its --app.

workflow

List, explain, plan, apply, or validate a workflow, or print an earlier run's report. plan and explain never write source. Only apply does, and only from a plan file.
Signature
Arguments
actionStringrequiredlist | explain | plan | apply | validate | report
What to do. Left out, it is asked for at a prompt.
workflowString
Needed by every action but list. What it names depends on the action; see Notes.
Options

repair

Run one narrow repair and print a structured report. Each kind is a known remedy for a known problem. dictionary and module-shape change nothing: they read akan doctor --strict, keep your module's findings, and name the command that fixes them.
Signature
Arguments
kindStringrequiredgenerated | format | imports | dictionary | module-shape
Which repair to run. What each one does is in Notes.
Options
--formatStringdefault markdownmarkdown | json · -o

On this page

Workflow CLI
Plan, Apply, Validate
Workflow Catalogue
workflow
repair
Workflow
sync
lint
typecheck
build
Create
create-module
✓
✓
create-scalar
✓
✓
create-ui
✓
✓
Add to a module
add-field
✓
✓
✓
add-enum-field
✓
✓
✓
add-mutation
✓
✓
✓
add-slice
✓
✓
✓
✓Run by validateNot run
Related Pages
Primitive Commands→
The commands a workflow applies through. You can also run them directly.
akan mcp→
Serves workflows and repairs to an agent as MCP tools.
--formatStringdefault markdownmarkdown | json · -o
markdown is for a person; json is the report an MCP client receives.
--outString-w
plan only. Writes the plan JSON here; without it the plan is only printed and cannot be applied.
--dry-runBooleandefault false-r
apply only. Reports the predicted apply without writing source; the run is still recorded.
--appString-a
Plan input: the target app or library. Every workflow requires it.
--moduleString-m
Plan input: the target domain, service or scalar module. All but create-scalar require it.
--fieldString-f
Plan input for add-field and add-enum-field: the field name.
--typeString-t
Plan input for add-field: a field type or scalar name. Use Int or Float, never Number.
--valuesString-l
Plan input for add-enum-field, or add-field with --type enum: comma-separated enum values.
--defaultString-d
Plan input: the field default, converted by type. An enum default must be one of the values.
--scalarString-c
Plan input for create-scalar: the scalar name.
--surfaceStringview | unit | template | zone | util · -u
Plan input for create-ui: the UI file to create. zone and util plan but do not apply.
--mutationString-n
Plan input for add-mutation: the mutation or action name.
--sliceString-i
Plan input for add-slice: the slice or query name.
Notes
NameDescription
explain · plan
workflow is a name from akan workflow list.
apply
workflow is the --out path, not a name; the run lands in .akan/workflows/runs/<runId>.json.
validate
workflow is a plan path, a run artifact path, or a runId, and validation is recorded as a run too.
report
workflow is a runId whose report is printed again, whether apply, dry run, validate or repair.
Examples
Output format. json is what an MCP client receives.
--appString-a
Target app or library. Required by generated, dictionary and module-shape.
--moduleString-m
Target module. Required by dictionary and module-shape.
--targetString-t
Target app, library or package. Required by format and imports.
Notes
NameDescription
generated
Runs akan sync <app>.
format · imports
Both run akan lint <target>; the kind only labels what the report is about.
dictionary
Report only: finds missing dictionary labels and points at akan add-field.
module-shape
Report only: finds a malformed module or a missing abstract and points at akan create-module.
afterwards
Every repair is recorded as a run and suggests akan doctor --strict --format json next.
over MCP
Apply mode serves repair_generated, repair_imports, repair_module_shape; others are CLI-only.
Examples
repair_imports · apply mode
akan repair module-shape
repair_module_shape · apply mode
akan workflow reportakan repair formatakan repair dictionary
CLI only