Epics, stories and tasks

Create, activate, advance and close the work, OPALE phase included.

epic_activate

effortless_epic_activate — Stability: beta · project

Activates an existing epic without going through a story. Refuses, by name, an unknown or Done epic and never creates one: use effortless_epic_start for that. Clears the active story, since a newly activated epic has none in progress. Idempotent.

💬 You ask your agent

« Make epic 012 the working epic again. »

→ The agent callseffortless_epic_activate

• epic_id = 012

Name	Type	Required	Description
epic_id	string	yes	Id of the existing epic to activate (not a default: there is no implicit target). Required.

epic_complete

effortless_epic_complete — Stability: stable · project

Closes an epic: each of its stories must be Done or superseded (an in-progress or suspended story blocks it, with a named refusal). Closing resolves no evolution: those still In progress are named in evolutions_maintained. Default: active epic.

💬 You ask your agent

« Close epic 012; all its stories are done. »

→ The agent callseffortless_epic_complete

• epic_id = 012

Name	Type	Required	Description
epic_id	string	no	Id of the epic to close (default: active epic).

epic_start

effortless_epic_start — Stability: stable · project

Creates (and optionally activates) an epic in a functional zone. Returns the id.

💬 You ask your agent

« Create an epic "Export overhaul" in the "reports" zone and activate it. »

→ The agent callseffortless_epic_start

• zone = rapports
• title = Export overhaul
• activate = true

Name	Type	Required	Description
zone	string	yes	Functional zone of the epic. Required.
title	string	yes	Title of the epic. Required.
description	string	no	Description of the epic (optional).
activate	boolean	no	If true (default), the created epic becomes the active epic and the active story pointer is cleared; false only creates it.

phase_eligibility

effortless_phase_eligibility — Stability: stable · project

Checks eligibility to move to the next OPALE phase (read-only).

💬 You ask your agent

« Am I eligible to move to the next phase? »

→ The agent callseffortless_phase_eligibility

No parameters.

phase_next

effortless_phase_next — Stability: stable · story

Advances the project to the next OPALE phase (server timestamp).

💬 You ask your agent

« Move the project to the next phase. »

→ The agent callseffortless_phase_next

No parameters.

story_activate

effortless_story_activate — Stability: stable · story

Activates an existing story (status Doing), reopening its epic if needed.

💬 You ask your agent

« Resume story 003 of epic 012. »

→ The agent callseffortless_story_activate

• story_id = 003
• epic_id = 012

Name	Type	Required	Description
story_id	string	yes	Id of the story to activate. Required.
epic_id	string	no	Parent epic of the story (default: resolved automatically).

story_archive

effortless_story_archive — Stability: beta · story

Archives a story that is already Done and closes the transaction of its act contracts: the .effortless/crew_contracts/<epic>/<story>/ folder is deleted. Refuses a story that is not Done. Idempotent. Default: the active story.

💬 You ask your agent

« Archive story 003; it is done. »

→ The agent callseffortless_story_archive

• story_id = 003

Name	Type	Required	Description
story_id	string	no	Id of the story to archive; it must be Done (default: active story).

story_complete

effortless_story_complete — Stability: stable · story

Closes a story: it must have at least one task, and all must be Done (otherwise a named refusal). Idempotent. Default: active story.

💬 You ask your agent

« Close the active story; all its tasks are done. »

→ The agent callseffortless_story_complete

Name	Type	Required	Description
story_id	string	no	Id of the story to close (default: active story).

story_items

effortless_story_items — Stability: stable · story

Lists the items (decisions, questions, tasks) of a given story.

💬 You ask your agent

« Show me the decisions, questions and tasks of story 003 in epic 012. »

→ The agent callseffortless_story_items

• epic_id = 012
• story_id = 003

Name	Type	Required	Description
epic_id	string	yes	Id of the epic that holds the story. Required.
story_id	string	yes	Id of the story whose decisions, questions and tasks are listed. Required.

story_objective

effortless_story_objective — Stability: beta · story

Sets or corrects a story's objective (one or two sentences), shown by the backlog on selection. Empty string: removes it.

💬 You ask your agent

« Set the objective of story 003: "Export monthly reports as CSV without losing accents." »

→ The agent callseffortless_story_objective

• story_id = 003
• objective = Export monthly reports as CSV without losing accents.

Name	Type	Required	Description
story_id	string	yes	Id of the target story. Required.
objective	string	yes	New objective, one or two sentences; an empty string removes it. Required.
epic_id	string	no	Parent epic of the story (default: resolved automatically).

story_pause

effortless_story_pause — Stability: beta · story

Suspends a story: sets the Suspended status, dates the pause, requires a reason and releases the active-story pointer. Touches no task, so resuming finds the workshop as it was left. Refuses a Done story and an empty reason. Idempotent. Resume with effortless_story_activate.

💬 You ask your agent

« Pause story 003, reason: we are waiting for the client's answer on the format. »

→ The agent callseffortless_story_pause

• story_id = 003
• reason = We are waiting for the client's answer on the format.

Name	Type	Required	Description
story_id	string	no	Id of the story to pause (default: active story).
reason	string	yes	Reason for the pause, recorded for the next reader; an empty reason is refused. Required.

story_reloop

effortless_story_reloop — Stability: stable · story

Loops the active story back to an earlier OPALE phase (rewind of the framing).

💬 You ask your agent

« Loop the active story back to the framing phase; the requirements changed. »

→ The agent callseffortless_story_reloop

• target_phase = P-cadrage

Name	Type	Required	Description
target_phase	string	yes	Id of the OPALE phase to rewind the active story to; it must come before the current phase (default workflow: O-analyse, P-cadrage, A-specs, L-plan, E-execute). Required.

story_retire

effortless_story_retire — Stability: beta · story

Retire une story NON COMMENCÉE, avec son motif (obligatoire) : statut Retired, elle cesse de bloquer la clôture de l'épic et peut être archivée, mais n'est jamais comptée comme livrée. Refuse une story déjà close, un motif vide, et une story dont une tâche est déjà Done (story_complete ou story_supersede alors).

💬 You ask your agent

« Retire story 007: the feature is dropped. »

→ The agent callseffortless_story_retire

• story_id = 007
• reason = fonctionnalité abandonnée

Name	Type	Required	Description
story_id	string	yes	Story à retirer (non commencée : aucune tâche Done).
reason	string	yes	Pourquoi elle ne sera pas faite — obligatoire.

story_start

effortless_story_start — Stability: stable · story

Creates (and optionally activates) a story in an epic. Returns the created id. kind: opale (default, with framing) or fix (direct fix: no framing, opened straight in the execution phase).

💬 You ask your agent

« Create a fix-type story "Fix accent in export" in epic 012 and activate it. »

→ The agent callseffortless_story_start

• epic_id = 012
• title = Fix accent in export
• kind = fix
• activate = true

Name	Type	Required	Description
epic_id	string	no	Epic that receives the story (default: active epic).
title	string	yes	Title of the story. Required.
slug	string	no	Explicit slug (default: derived from the title).
zone	string	no	Functional zone of the story (default: the zone of the parent epic).
depends_on	array<string>	no	Ids the story depends on (default none).
activate	boolean	no	If true, activates the created story immediately; default false.
kind	string	no	Story type: opale (default), or fix for a direct correction that skips the framing documents and starts in the execution phase.
taskless_reason	string	no	Reason why this story will have NO task (pure framing, milestone, decision); giving it clears the taskless flag so the audit stops counting the story as an oversight.
objective	string	no	Objective of the story in one or two sentences, shown by the backlog when the story is selected.

story_supersede

effortless_story_supersede — Stability: beta · story

Marks a story as superseded by another story of the same epic: it no longer blocks epic closure and is not counted as delivered.

💬 You ask your agent

« Story 004 is replaced by 006: mark it as superseded. »

→ The agent callseffortless_story_supersede

• story_id = 004
• by = 006

Name	Type	Required	Description
story_id	string	yes	Id of the superseded story, which will never be delivered; a story already closed is refused. Required.
by	string	yes	Id of the story that carried the work instead, in the same epic. Required.

task_add

effortless_task_add — Stability: stable · story

Adds a task (status Todo) to a story. Returns the id (TSK-NN). stack: development norms that apply to the task (refused if a norm does not exist). Optional routing classification at creation (complexity, capability_tier, effort_level), readable afterwards via effortless_task_route_show.

💬 You ask your agent

« Add a task "Write the parser tests" to the active story. »

→ The agent callseffortless_task_add

• title = Write the parser tests

Name	Type	Required	Description
title	string	yes	Title of the task. Required.
description	string	no	Description of the task (default empty).
phase	string	no	OPALE phase of the task, as a workflow phase id (default: the current phase of the story).
epic_id	string	no	Target epic (default: active epic).
story_id	string	no	Target story (default: active story).
stack	array<string>	no	Development norms that apply to the task, named like the folders of .ai/ndd/ (for example ["rust", "tauri"]); the agent receives only these. A norm that does not exist is refused.
complexity	string	no	Complexity of the task: simple or complex.
capability_tier	string	no	Capability tier for routing: deep, standard or light.
effort_level	string	no	Effort requested for routing: low, medium or high.

task_update

effortless_task_update — Stability: stable · story

Changes the status (Todo / Doing / Done), title, description and/or result of a task. At least one field is required. Moving to Doing is refused while the story's framing is incomplete or a task it depends on is not Done.

💬 You ask your agent

« Set task TSK-02 of story 003 in epic 012 to Doing. »

→ The agent callseffortless_task_update

• epic_id = 012
• story_id = 003
• task_id = TSK-02
• status = Doing

Name	Type	Required	Description
epic_id	string	yes	Id of the epic that holds the task. Required.
story_id	string	yes	Id of the story that holds the task. Required.
task_id	string	yes	Id of the task to update (for example TSK-01). Required.
status	string	no	New status: Todo, Doing or Done; at least one field to change is required.
title	string	no	New title of the task.
description	string	no	New description (the objective of the task); an empty string removes it.
result	string	no	What the task produced, as observed (files, verbs, measurements); an empty string removes it.