Frame work with OPALE

An OPALE story is prepared before it is coded: analysis, framing, specifications, plan, then execution. You come here when you want to set out the problem with your agent, record decisions and questions, or, on the contrary, fix a defect without ceremony.

What you ask the agent

💬 You ask your agent

« Create the framing documents for story 003 of epic 012. »

→ The agent callseffortless_cadrage_docs_scaffold

• epic_id = 012
• story_id = 003

💬 You ask your agent

« Record, on story 003 of epic 012, the decision "Export as CSV" in the framing phase, because Excel must open the exports; consequence: handle the encoding; ruled-out alternative: JSON. »

→ The agent callseffortless_decision_add

• epic_id = 012
• story_id = 003
• title = Export as CSV
• context = Excel must open the exports
• decision = Export as CSV
• consequences = Handle the encoding
• rejected_alternatives = JSON
• phase = P-cadrage

💬 You ask your agent

« On story 003 of epic 012, ask the authentication question in the framing phase: context, the application will be multi-user; impact, nothing moves forward without an answer; suggestion, OAuth2. »

→ The agent callseffortless_question_ask

• epic_id = 012
• story_id = 003
• question = Which authentication?
• context = The application will be multi-user
• impact = Nothing moves forward without an answer
• suggestion = OAuth2
• phase = P-cadrage

💬 You ask your agent

« Can we move to the next phase? »

→ The agent callseffortless_phase_eligibility

💬 You ask your agent

« List the project's decisions and open questions. »

→ The agent callseffortless_decisions_list

💬 You ask your agent

« Suggest three stories to break this epic down: CSV export, Excel export, archiving. I will validate them. »

→ The agent callseffortless_draft_add

• title = CSV export

💬 You ask your agent

« It is a small fix, "Fix the accent in the export": open a direct fix story, without framing. »

→ The agent callseffortless_story_start

• title = Fix the accent in the export
• kind = fix

💬 You ask your agent

« Which acceptance scenarios are still to be verified? »

→ The agent callseffortless_recipe_maturity

What the agent does

Prepare a story's documents

1. effortless_cadrage_docs_scaffold with epic_id and story_id: creates the story's missing OPALE documents in blueprints/ and returns the files created. Documents already there are left alone.
2. effortless_cadrage_layer_next: at project level, tells which framing layer to write next among the four root blueprints.

Move through the phases

An OPALE story goes through five phases: O-analyse, P-cadrage, A-specs, L-plan, E-execute.

1. effortless_phase_eligibility: read-only. Tells whether the current phase's required documents exist and which phase comes next.
2. effortless_phase_next: moves to the next phase, with the date set by the server. The engine redoes the check on its side.
3. effortless_story_reloop, when the framing has to be redone: target_phase names a phase earlier than the current one.

As long as the story is before the E-execute phase, a task cannot move to In progress (see Run the work).

Record decisions

1. effortless_decision_add: a decision (ADR) attached to a story. The agent fills in epic_id, story_id, title, context, decision, consequences, rejected_alternatives and the OPALE phase concerned. The engine returns the DEC-NN identifier.
2. effortless_decisions_list: all the project's decisions, with their epic and story of origin.

Ask and resolve questions

1. effortless_question_ask: an open question on a story (question, context, impact, suggestion, phase). The engine returns Q-NN.
2. effortless_question_resolve: resolves it with its answer.
3. effortless_questions_list: all the project's questions.

Big open questions (BQO)

A BQO is a question asked at project level, not on a story.

1. effortless_bqo_ask: records it.
2. effortless_bqo_list: lists them.
3. effortless_bqo_resolve: answers it (question_id, answer).
4. effortless_bqo_graduate: if it deserves a project of its own, copies it into an existing epic (epic_id). It does not create an epic; the question is no longer answered at project level but from that epic.

Story drafts

To break an epic down without creating the stories right away.

1. effortless_draft_add: a draft (title, summary, kind opale or fix, proposed tasks, rationale, dependencies) in the active epic or the named one.
2. effortless_draft_update: edits a draft; anything not passed stays unchanged.
3. effortless_draft_list: lists an epic's drafts.
4. effortless_draft_submit: submits it for your review.
5. effortless_draft_validate: turns it into a real story and returns the identifier created.
6. effortless_draft_reject: sets it aside.

The agent submits; you are the one who says validate or reject.

Proposals on a story

A proposal is a summary attached to a story, waiting for your verdict.

1. effortless_proposal_add: adds it (pending) to the active story, or to story_id.
2. effortless_proposal_validate: validates it.
3. effortless_proposal_reject: rejects it.

The short route: a fix

For a defect to fix right now, the agent does not need to frame anything.

1. effortless_story_start with kind: "fix": the story needs no framing and opens directly in the execution phase. With activate: true, it becomes the active story.
2. effortless_task_add then effortless_task_update: the rest goes as for a normal story (Run the work).

Acceptance scenarios and proofs

1. effortless_recipe_maturity: read-only. Sorts the acceptance scenarios by maturity (stable, candidate, beta, planned), returns what remains to be done and the scenarios blocked by a gap. Optionally limited to one epic_id or story_id.
2. effortless_interruption_proof: proves that a write order survives a real interruption. The engine kills the declared command (SIGKILL) at each position it announces, then runs the state check. proof_id names a proof you declared in effortless.json under settings.interruption_proofs; positions restricts the cuts (by default, all of them).

What you get

• Framing documents in blueprints/, in Markdown, to read in your editor.
• Decisions and questions in the Knowledge screen, with their origin.
• Stories, their phase and their drafts in the Backlog (the Drafts, Proposal and Reloop blocks on the epic and story pages).
• Open questions and unverified acceptance scenarios under Waiting for you on the Dashboard.

When the agent is refused

Situation	What the refusal says	What to do
A task moves to In progress while the story's framing is unfinished	cadrage:phaseIncomplete	Provide the phase's missing documents, or open a direct fix with story_start and kind: "fix".
Moving to the next phase, required documents missing	pilotage:phaseMissingDocs	Write the documents the refusal names.
Moving to the next phase while the story is already in the last phase	pilotage:phaseAlreadyLast	Nothing to lift: close the story, or reloop it to an earlier phase.
Phase already completed	pilotage:phaseAlreadyCompleted	Move to the next phase, or go back with story_reloop.
A decision with an escaped HTML entity in a field (for example &)	cadrage:entiteHtml	Rewrite the field without the entity.
Resolving at project level a BQO already graduated into an epic	cadrage:questionGraduated	Answer from the BQOs of the epic that holds it, with question_resolve.
Unknown BQO	cadrage:questionNotFound	List the BQOs with bqo_list and use the right identifier.
Reading a story's items without naming the epic and the story	pilotage:noStoryTarget	Pass epic_id AND story_id; project_tree names them.
Interruption proof not declared	proof:unknown	Declare it in settings.interruption_proofs of effortless.json.
Proof whose command announces no position	proof:noPosition	Have the command write EFFORTLESS-POS <n> at each cut point.
Proof whose command cannot be launched	proof:launchFailed	Check the declared command.